An application that serves up documentation stored in a git repository rendered via Hugo using the Docsy template.
The application checks out the designated repository and renders all the documentation that it then serves over HTTP.
It checks for updates to the repo every five minutes, pulling and re-rendering the documentation.
In addition it understands the Gerrit code review system and allows for previewing changes to documentation by visiting any URL into the documentation with a cl query parameter, e.g. ?cl=NNNNN and the documentation with that reviews most recent changes to the documentation patched in and rendered.
The detailed design doc is at http://go/docsyserver.
BUILD.bazel - Builds a Docker container that contains a checkout of the Docsy example repo, along with all the dependencies needed to build it, including Hugo and npm. All third-party dependencies are contained in the gcr.io/skia-public/docsyserver-base base container, which is also built with rules in this file.
go/docsyserver - The application.
go/codereview - An abstraction of the functionality used from Gerrit. In theory a new implementation of CodeReview could be made that supports GitHub or other code review systems.
go/docsy - An abstraction of running the hugo executable over the source documentation using the Docsy template.
go/docset - Manages checking out the repo, patching CLs for documentation under code review, and cleaning up after code review issues are closed.
images/head-end.html - If there are script sources that need to be added to each page those should go in this file, which will be placed in the right directory in the docsy template.
To build a local docker image run:
$ make
This will build the executable and store it at $GOPATH/bin/docsyserver.
First build the docker image, which only needs to be done once:
$ make build-local-image
Then run a local instance, changing $(SKIA) to the local checkout of Skia:
docker run --entrypoint=/serve.sh -ti -p 1313:1313 --user=root -v $(SKIA)/site:/input bazel/docsyserver:docsyserver_container
The content will now be available at localhost:1313. The server will automatically re-render the HTML and refresh the page as the source documents are edited, there's no need to restart the server after you make documentation changes.
To run, execute the docker image and supply the following flags:
$ docsyserver --local [flags]
-alsologtostderr
log to standard error as well as files
-doc_path string
The relative directory, from the top of the repo, where the documents are located. (default "site")
-doc_repo string
The repo to check out. (default "https://skia.googlesource.com/skia")
-gerrit_url string
The gerrit URL. (default "https://skia-review.googlesource.com")
-hugo string
The absolute path to the hugo executable. (default "hugo")
-port string
HTTP service address (e.g., ':8000') (default ":8000")
You must have the gcloud command line tool installed and authorized, as that's how docsyserver with the --local flag will create an OAuth 2.0 bearer token to access Gerrit. You will also need a local checkout of the Docsy example project and Hugo installed. See the Docsy docs for installation instructions.
The full set of flags are:
-alsologtostderr
log to standard error as well as files
-doc_path string
The relative directory, from the top of the repo, where the documents are located. (default "site")
-doc_repo string
The repo to check out. (default "https://skia.googlesource.com/skia")
-docsy_dir string
The directory where docsy is found. (default "../../docsy-example")
-gerrit_url string
The gerrit URL. (default "https://skia-review.googlesource.com")
-hugo string
The absolute path to the hugo executable. (default "hugo")
-local
Running locally if true. As opposed to in production.
-log_backtrace_at value
when logging hits line file:N, emit a stack trace
-log_dir string
If non-empty, write log files in this directory
-logtostderr
log to standard error instead of files
-port string
HTTP service address (e.g., ':8000') (default ":8000")
-prom_port string
Metrics service address (e.g., ':10110') (default ":20000")
-stderrthreshold value
logs at or above this threshold go to stderr
-v value
log level for V logs
-vmodule value
comma-separated list of pattern=N settings for file-filtered logging
-work_dir string
The directory to check out the doc repo into. (default "/tmp")