Documentation
Tilegroxy documentation is written in AsciiDoc files stored in the same repository as code. Tilegroxy uses Antora to build its documentation into a website that can be served up inside the application as well as a common server.
The documentation is automatically built via github actions as a test on every PR and commit to main. The documentation is only published to the doc server upon new releases.
If you are making changes to the asciidocs, please build the documentation before opening a PR. Do not commit any changes to internal/website/resources
- the folder is git ignore
-ed however index.html has a default placeholder in git. You can avoid changes from index.html showing up in git using git update-index --no-assume-unchanged
Build
The Makefile contains a couple targets specific to the documentation
Docs
Running make docs
will invoke antora to build the documentation. You must invoke this goal before building the go application in order to have the website available inside of tilegroxy.
Antora is a node app and the make command will automatically install the dependency before invoking it. You should use node 20 for building documentation.
The docs are built in build/site
and then copied into the internal/website/resources
where go:embed
can pull them into the tilegroxy binary.
The UI template lives at https://github.com/tilegroxy/antora-ui and any changes to it will need to be built prior to building documentation in this repository by creating a tag in the form vN
in that repository and then updating antora-playbook.yml
in this repository to refer to that new version.
Readme
Github does not support include
pragmas (see github/markup#1095) so it’s necessary to pre-bake the `include`s ahead of time.
This is performed using asciidoctor-reducer via running make readme
. This requires you have a somewhat modern ruby & gem installed.
We use this to allow our main README file to share content with the main documentation website. The README.adoc
file should not be modified itself, instead any modifications should be made to README_source.adoc
and then make readme
run to update the main README. The command should also be run any time an included doc is updated. This is not yet automated.