mirror of https://github.com/hpcaitech/ColossalAI
[doc] fixed typos in docs/README.md (#3082)
parent
10c61de2f7
commit
3213347b49
|
@ -14,7 +14,7 @@
|
||||||
|
|
||||||
## 📝 Overview
|
## 📝 Overview
|
||||||
|
|
||||||
We evaluated various existing solutions for documentation in the community and discussed their advantages and disadvangtes in the [issue #2651](https://github.com/hpcaitech/ColossalAI/issues/2651). Therefore, we propose to build a more modern and robust documentation system by integrating the Sphinx [autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) function and the [Docusaurus](https://docusaurus.io/) framework.
|
We evaluated various existing solutions for documentation in the community and discussed their advantages and disadvantages in the [issue #2651](https://github.com/hpcaitech/ColossalAI/issues/2651). Therefore, we propose to build a more modern and robust documentation system by integrating the Sphinx [autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) function and the [Docusaurus](https://docusaurus.io/) framework.
|
||||||
|
|
||||||
## 🗺 Module Structure
|
## 🗺 Module Structure
|
||||||
|
|
||||||
|
@ -29,15 +29,15 @@ We evaluated various existing solutions for documentation in the community and d
|
||||||
```
|
```
|
||||||
|
|
||||||
The documentation module structure is shown above:
|
The documentation module structure is shown above:
|
||||||
1. source: This folder contains the multi-language documentation files.
|
1. source: This folder contains multi-language documentation files.
|
||||||
2. `sidebars.json`: The `sidebars.json` defines the table of content for the tutorials. You need to update this file when a new doc is added/deleted.
|
2. `sidebars.json`: The `sidebars.json` defines the table of content for the tutorials. You need to update this file when a new doc is added/deleted.
|
||||||
3. `versions.json`: The `versions.json` in the **main branch** in the **latest commit** will be used to control the versions to be displayed on our website
|
3. `versions.json`: The `versions.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
|
## 🧱 Our Documentation System
|
||||||
|
|
||||||
We believe that there are several advantages from the existing system can be combined for simplicity, usability and maintainability:1
|
We believe that the combination of the existing systems can yield several advantages such as simplicity, usability and maintainability:
|
||||||
1. Support Markdown](https://www.markdownguide.org/), we belive is a more popular language for writing documentations comapred to [RST](https://docutils.sourceforge.io/rst.html).
|
1. Support [Markdown](https://www.markdownguide.org/). We believe is a more popular language for writing documentation compared to [RST](https://docutils.sourceforge.io/rst.html).
|
||||||
2. Support Autodoc, which can automatically generate documentation from the docstrings in the source code provided by [Sphinx](https://www.sphinx-doc.org/en/master/).
|
2. Support Autodoc. It can automatically generate documentation from the docstrings in the source code provided by [Sphinx](https://www.sphinx-doc.org/en/master/).
|
||||||
3. Support elegant and modern UI, which is provided by [Docusaurus](https://docusaurus.io/).
|
3. Support elegant and modern UI, which is provided by [Docusaurus](https://docusaurus.io/).
|
||||||
4. Support MDX for more flexible and powerful documentation, which is provided by [Docusaurus](https://docusaurus.io/).
|
4. Support MDX for more flexible and powerful documentation, which is provided by [Docusaurus](https://docusaurus.io/).
|
||||||
5. Support hosting blogs/project home page/other pages besides the documentation, which is provided by [Docusaurus](https://docusaurus.io/).
|
5. Support hosting blogs/project home page/other pages besides the documentation, which is provided by [Docusaurus](https://docusaurus.io/).
|
||||||
|
@ -46,7 +46,7 @@ Therefore, we have built the [ColossalAI-Documentation](https://github.com/hpcai
|
||||||
|
|
||||||
## 🎊 Contribution
|
## 🎊 Contribution
|
||||||
|
|
||||||
You can contribute to the documentation by directly set up a Pull Request towards the `docs/source` folder. There are several guidelines for documentation 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.
|
||||||
|
|
||||||
1. The documentation is written in Markdown. You can refer to the [Markdown Guide](https://www.markdownguide.org/) for the syntax.
|
1. The documentation is written in Markdown. You can refer to the [Markdown Guide](https://www.markdownguide.org/) for the syntax.
|
||||||
2. You must ensure that the documentation exists for all languages. You can refer to the [Adding a New Documentation](#-adding-a-new-documentation) for more details.
|
2. You must ensure that the documentation exists for all languages. You can refer to the [Adding a New Documentation](#-adding-a-new-documentation) for more details.
|
||||||
|
@ -68,7 +68,7 @@ Let's assume that you want to add a file called `your_doc.md`, your file structu
|
||||||
- sidebars.json # add your documentation file name here
|
- 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 a documentation exists for all languages and can be used to build the website successfully.
|
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
|
### 🧹 Doc Testing
|
||||||
|
|
||||||
|
@ -78,7 +78,7 @@ Every documentation is tested to ensure it works well. You need to add the follo
|
||||||
<!-- doc-test-command: $command -->
|
<!-- doc-test-command: $command -->
|
||||||
```
|
```
|
||||||
|
|
||||||
Meanwhile, only code labelled as a Python code block will be considered for testing.
|
Meanwhile, only code labeled as a Python code block will be considered for testing.
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
```python
|
```python
|
||||||
|
@ -98,13 +98,13 @@ Lastly, if you want to skip some code, you just need to add the following annota
|
||||||
<!--- doc-test-ignore-end -->
|
<!--- 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.
|
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
|
### 💉 Auto Documentation
|
||||||
|
|
||||||
Lastly, you may want to include the API documentation for a class/function in your documentation for reference.
|
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 elegant display.
|
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](https://github.com/hpcaitech/ColossalAI-Documentation/pull/175).
|
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](https://github.com/hpcaitech/ColossalAI-Documentation/pull/175).
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
|
|
Loading…
Reference in New Issue