This repo houses all the assets used to build the Jaeger website, available at https://jaegertracing.io.
The site is built and hosted by Netlify.
Install the "extended" Hugo binary from hugo/releases (use one of the hugo_extended_*
binaries) or
use a package manager if it is available for your operating system.
The "extended" version of Hugo supports Sass, which is necessary to build the site locally.
The currently used version of Hugo is defined in the netlify.toml
configuration file.
If you want to develop the site locally, you can run a single command (assuming that you've run the setup):
$ make develop
This will start up a local server on localhost port 1313. When you make changes to either the content of the website (in content
) or to the Sass and JavaScript assets of the page (in themes/jaeger-docs/assets
), the browser will automatically update to reflect those changes (usually in under one second).
The site is published automatically by Netlify whenever changes are merged to the master
branch. The site cannot be published in an ad-hoc way (e.g. through a make
command or script in the repo).
We strongly encourage you to contribute to this site! For more information, see the contributing guide.
Diagrams included in the documentation are created in the shared Google Slides document, which supports export to SVG. If you need to make changes to the diagrams as part of a PR, please copy the diagram into a new slide deck and include a shared link to it in the PR along with the exported SVG file. The maintainers will update the master deck with the new version upon merging the PR.
Each Jaeger version is documented in a separate directory e.g. content/docs/1.8/. A special directory content/docs/next-release/ is reserved for the changes to be published as the next version. If you are adding documentation for features that are not yet released in the main Jaeger repository, add your changes to the next-release
directory. If you're adding documentation for already released features, you may need to make the same change twice, i.e. in the most recent release (e.g. 1.8
) and in the next-release
directories.
Before creating a new release, make sure all outstanding PRs for that version are merged to next-release
directory. Then create a release by pushing a tag release-X.Y.Z
, ex git tag release-1.12.0; git push origin release-1.12.0
.
Note: next release automation currently does not include generation of CLI flag docs.
The docs for the Jaeger CLI tools are generated using the docs
command with their respective Docker images, automated with the following script:
python ./scripts/gen-cli-data.py ${VERSION_MAJOR_MINOR}
The script requires data/cli/${VERSION}/config.json
file that describes the binaries and their storage options. When cutting a new release this file should be copied from the previous release, and adjusted as needed (e.g. if new storage option is implemented). The script generates YAML files in data/cli/${VERSION}
directory.
There are five admonition types available for the Jaeger docs:
Admonition type | Color
:===============|:=====
info
| blue
success
| green
danger
| red
warning
| yellow
requirement
| purple
Here's an example:
{{< danger >}}
We do not recommend that you do this!
{{< /danger >}}
You can also add titles:
{{< success title="New feature" >}}
Jaeger now supports a new thing that you definitely want.
{{< /success >}}