We prefer simplicity and currently use GitHub page to host Venice documentation. Those documentation will be built automatically by GitHub pipelines in the
It is strongly encouraged that any code change which affects the validity of information in the docs also include updates to the docs, so that both are kept in sync atomically.
Experimental functionalities and future plans are also worth documenting, though they must be clearly marked as such, so that users and operators reading those docs can make informed decisions about the level of risk they are willing to take on if trying out a given functionality. If the level of maturity of a given functionality is not called out, then it implicitly means that the functionality is considered mature and its API is unlikely to change. Undocumented configs and APIs may or may not be considered mature and stable, and if in doubt, it is appropriate to open an Issue to request that it be explicitly documented.
In general, it is recommended to get familiar with the docs before writing more docs, to try to keep the style and structure coherent. That being said, even if unsure where some documentation belongs, do err on the side of including it (anywhere), and reviewers may suggest placing it elsewhere.
In order for your docs to be rendered properly in the documentation hierarchy, Venice developers need to add a header section at the top of each documentation. The
title section will be what the end user sees in the sidebar, and the
parent section represents the parent page of the current page for linking purpose. The
permalink section will be the URL path where the page will be served. An example of the header is below:
--- layout: default title: Documentation Guideline parent: Developer Guides permalink: /docs/dev_guide/documentation_guideline ---
A page in the middle of the hierarchy has both the
has_children attributes. For example:
--- layout: default title: Write APIs parent: User Guides has_children: true permalink: /docs/user_guide/write_api ---
For a deeply nested page, a
grand_parent attribute is also required. For example:
--- layout: default title: Push Job parent: Write APIs grand_parent: User Guides permalink: /docs/user_guide/write_api/push_job ---
Note that for now, the doc supports at most 3 levels of nesting.
For more information, consult Just the Docs.
Here’s a link to all the emojis available in README files: Emoji Cheat Sheet. If you want to find a good emoji, you can use this website.
Testing Doc Changes
A GitHub fork can have its own documentation. This can be setup by:
- Navigating to the fork’s Settings > Pages, i.e.:
- Selecting which branch to publish the docs from.
/docsas the root directory.
- Clicking Save.
- Navigating to your fork’s docs at: