Updating the docs
If you want to open a PR on Gaia to update the documentation, please follow the guidelines in the
Docs Build Workflow
The documentation for Gaia is hosted at:
built from the files in this (
/docs) directory for master
How It Works
There is a CircleCI job listening for changes in the
/docs directory, on both
develop branches. Any updates to files in this directory
on those branches will automatically trigger a website deployment. Under the hood,
the private website repository has a
make build-docs target consumed by a CircleCI job in that repo.
The README.md is also the landing page for the documentation on the website. During the Jenkins build, the current commit is added to the bottom of the README.
The config.js generates the sidebar and Table of Contents on the website docs. Note the use of relative links and the omission of file extensions. Additional features are available to improve the look of the sidebar.
NOTE: Strongly consider the existing links - both within this directory and to the website docs - when moving or deleting files.
Relative links should be used nearly everywhere, having discovered and weighed the following:
Where is the other file, relative to the current one?
- works both on GitHub and for the VuePress build
- confusing / annoying to have things like:
- requires more updates when files are re-shuffled
Where is the other file, given the root of the repo?
- works on GitHub, doesn't work for the VuePress build
- this is much nicer:
- if you move that file around, the links inside it are preserved (but not to it, of course)
The full GitHub URL to a file or directory. Used occasionally when it makes sense to send users to the GitHub.
To build and serve the documentation locally, run:
npm install -g vuepress
then change the following line in the
Finally, go up one directory to the root of the repo and run:
# from root of repo vuepress build docs cd dist/docs python -m SimpleHTTPServer 8080
then navigate to localhost:8080 in your browser.
Build RPC Docs
make tools from the root of repo, to install the swagger-ui tool.
Then, edit the
swagger.yaml manually; it is found here
make update-gaia-lite-docs from the root of the repo.
Because the build processes are identical (as is the information contained herein), this file should be kept in sync as much as possible with its counterpart in the Tendermint Core repo.
Update and Build the RPC docs
- Execute the following command at the root directory to install the swagger-ui generate tool.
- Edit API docs
swagger.yamland replace the old
- Compile gaiacli