Creating a Documentation for DevStream¶
- We use readthedocs to host our documentation. You do not need to know too much more about it in order to create a doc for DevStream, though.
- Readthedocs supports both
mkdocsto build the doc site; we use
mkdocsat the moment. If you meet any issues, the official doc of
mkdocshere is a good place to start.
- In our mkdocs setup, we use the
materialtheme. More info on "material":
- We also use two plugins for mkdocs:
- Python3 (
mkdocsis a Python thing)
- pip3 (to install dependencies)
Suggested setup for macOS users:
- use brew to setup Python
pip3 install -r docs/requirements.txt
The root folder of
mkdocs is at
The main config is
/mkdocs.yml, and the docs folder is
Currently, we support two languages: - en - zh
It's worth noting that the "search" function doesn't work for "zh" (a limitation of
mkdocs' search function.)
For each English document, there is a Chinese translation in a separate file.
If the English document's filename is
doc_name.md, there should also be a file named
doc_name.zh.md. To create a Chinese translation, put the translation into
doc_name.zh.md. This file is the translation of
Create a New Documentation¶
To create new documentation, do the following:
/docsfolder. You can put them under a subfolder if necessary. Refer to the current directory structure and use your best judgment to decide the best place for that new doc.
- Write the content of the doc. You can choose to write only the English doc or the Chinese doc; you don't have to (but it's highly recommended if you can) write documentation in both languages.
- In most cases, you don't need to think about the navigation menu which is the table of content of the whole doc website. But If you need to customize the navigation menu, you can refer to Setting up Navigation.
Setting up Navigation¶
If you want to customize the navigation menu, you can update
nav: section in
mkdocs.yaml. We support wildcards and subdirectory cross-link. For example:
- Normally, 'contributing_guide*.md' will be expanded to 'contributing_guide.md' and 'contributing_guide.zh.md'
- If you create documentation in the
best-practices/directories, you will not need to update the
Review Your Change Locally¶
Review your changes before submitting a PR.