20d1c99444
* refactor: README-zh-Hans * refactor: REFERENCE * docs: update paths in README |
||
---|---|---|
.. | ||
source | ||
README-zh-Hans.md | ||
README.md | ||
REFERENCE.md | ||
conda-doc-test-deps.yml | ||
requirements-doc-test.txt | ||
sidebars.json | ||
versions.json |
README.md
๐ Documentation
๐ Table of Contents
๐ Overview
We evaluated various existing solutions for documentation in the community and discussed their advantages and disadvantages in the issue #2651. Therefore, we propose to build a more modern and robust documentation system by integrating the Sphinx autodoc function and the Docusaurus framework.
๐บ Module Structure
- docs
- source
- en
- zh-Hans
- sidebars.json
- versions.json
- requirements-doc-test.txt
The documentation module structure is shown above:
- source: This folder contains multi-language documentation files.
sidebars.json
: Thesidebars.json
defines the table of content for the tutorials. You need to update this file when a new doc is added/deleted.versions.json
: Theversions.json
in the main branch in the latest commit will be used to control the versions to be displayed on our website
๐งฑ Our Documentation System
We believe that the combination of the existing systems can yield several advantages such as simplicity, usability and maintainability:
- Support Markdown. We believe is a more popular language for writing documentation compared to RST.
- Support Autodoc. It can automatically generate documentation from the docstrings in the source code provided by Sphinx.
- Support elegant and modern UI, which is provided by Docusaurus.
- Support MDX for more flexible and powerful documentation, which is provided by Docusaurus.
- Support hosting blogs/project home page/other pages besides the documentation, which is provided by Docusaurus.
Therefore, we have built the ColossalAI-Documentation repository to integrate the features above.
๐ Contribution
You can contribute to the documentation by directly setting up a Pull Request towards the docs/source
folder. There are several guidelines for documentation contribution.
- The documentation is written in Markdown. You can refer to the Markdown Guide for the syntax.
- You must ensure that the documentation exists for all languages. You can refer to the Adding a New Documentation for more details.
- You must provide a test command for your documentation, please see Doc Testing for more details.
- You can embed your docstring in your markdown, please see Auto Documentation for more details.
๐ Adding a New Documentation
You can add a Markdown file to the docs/source
folder. You need to ensure that multi-language is supported in your PR. Let's assume that you want to add a file called
your_doc.md`, your file structure will look like this.
- docs
- source
- en
- your_doc.md # written in English
- zh-Hans
- your_doc.md # written in Chinese
- sidebars.json # add your documentation file name here
Meanwhile, you need to ensure the sidebars.json
is updated such that it contains your documentation file. Our CI will check whether documentation exists for all languages and can be used to build the website successfully.
๐งน Doc Testing
Every documentation is tested to ensure it works well. You need to add the following line to the bottom of your file and replace $command
with the actual command. Do note that the markdown will be converted into a Python file. Assuming you have a demo.md
file, the test file generated will be demo.py
. Therefore, you should use demo.py
in your command, e.g. python demo.py
.
<!-- doc-test-command: $command -->
Meanwhile, only code labeled as a Python code block will be considered for testing.
```python
print("hello world")
```
Lastly, if you want to skip some code, you just need to add the following annotations to tell docer
to discard the wrapped code for testing.
<!--- doc-test-ignore-start -->
```python
print("hello world")
```
<!--- doc-test-ignore-end -->
If you have any dependency required, please add it to requriements-doc-test.txt
for pip and conda-doc-test-deps.yml
for Conda.
๐ Auto Documentation
Lastly, you may want to include the API documentation for a class/function in your documentation for reference.
We support autodoc
to extract the docstring and transform it into a Web element for an elegant display.
You just need to add {{ autodoc:<mod-name> }}
in your markdown as a single line. An example is given below and you can see the outcome in this PR.
{{ autodoc:colossalai.amp.apex_amp.convert_to_apex_amp }}