If you are contributing to the repository, make sure to fork this repo, and then clone your own fork. You will need to do this to make creating pull requests easier.
git clone https://github.com/<your-username>/terra-docsUsing Docker is easier than configuring your local machine to build sphinx:
First build the local Docker container:
make docker-make
Then you're ready to build the site:
make docker-build
You can view the site in your browser by navigating to index.html located in <PATH_TO_CLONED_REPO>/_build/html/index.html.
Make sure to run make docker-build each time you save your changes to view them live.
To auto-rebuild the site and refresh the browser use:
make docker-watch
Pages can be written in markdown .md or restructured text .rst
Add new pages to the /docs/ folder. Link pages to the navigation by inputting their relative filepath in the toctree located in index.md. Second-level pages can be made by adding a toctree to a parent file.
Markdown example:
To link a top-level page, insert a toctree and filepath into index.md:
```{toctree}
:hidden:
/docs/top-level-page
/docs/other-top-level-page
```
This will list top-level-page in the navigation.
To link a second-level page, add a filename's relative path to the toctree in the parent file.
In top-level-page.md, input the following toctree
```{toctree}
:hidden:
/docs/second-level-page
```
These two examples together will create the following navigation:
Top level page
- Second level page
Other top level page
All links written in markdown are relative. Full URLs will render as external filepaths.
Admonitions are made in markdown with the following syntax:
:::{warning}
This is the body of my warning admonition.
:::
Custom admonition syntax:
:::{admonition} This is my custom admonition title
:class: warning
This is the body of my admonition
:::
For a list of all admonition types, visit https://sphinx-book-theme.readthedocs.io/en/latest/reference/kitchen-sink/paragraph-markup.html?highlight=admonition#admonitions
Each module should be documented with the following subheaders:
-
Abstract (no header)
Maximum 2 paragraphs to explain, in broad terms, the general purpose of the module, to provide a "big-picture" perspective of how the module provides functionality and organization to the Terra protocol, and how it interacts with other modules.
-
Concepts
A section dedicated to the concepts that are required to understand how the module works. This may include:
- layman primer
- math formulas (formatted with LaTeX)
- diagrams
-
Data
A section that covers the various data structures used by the module.
-
State
A section that covers the keeper state for that module key-value store
-
Messages
A section that covers the various types of messages and gives a rough explanation on how they are handled.
-
Proposals
A section that covers the related governance proposals
-
Transitions
A section that covers the begin-blocker and end-blocker transition functions
-
Parameters
A section that covers the chain parameters that can be modified by governance via the
paramsmodule
- Sphinx Book Theme for theme elements.
- Myst parser for markdown syntax.
- Sphinx-design for tabs, cards, grids, dropdowns, and classes.
Extensions should be added to requirements.txt and conf.py.
Redirects are listed in conf.py. Visit https://documatt.gitlab.io/sphinx-reredirects/ for more info.
Built using Sphinx Book Theme. Visit https://sphinx-book-theme.readthedocs.io/en/latest/customize/custom-css.html for CSS customization.
This software is licensed under the MIT license. See LICENSE for full disclosure.
© 2022 Terraform Labs, PTE.
