Set up Sphnix#

Install Sphinx:

pip install sphinx

Create a directory inside the project to hold the docs:

cd /path/to/project
mkdir docs

Run sphinx-quickstart to create the basic configuration in docs:

cd docs
sphinx-quickstart

Then, you will have index.rst, a conf.py and some other files. If you want to use Markdown instead, you have to firstly follow the installation steps in Installation of Markdown and you can replace index.rst with index.md. Build the docs into html to see how they look:

make html

The documentation index.rst (or index.md if you use Markdown) will be built as index.html in the output directory _build/html/index.html. You can check it by open index.html with any web browser.

Installation of Markdown

Both Markdown and reStructuredText can be used in the Sphnix project. You can install the Markdown setting by the following steps:

pip install myst-parser

Add it in the conf.py:

extensions = ["myst_parser"]

You need to identify the Table of Contents Tree in the docs/index.md. toctree tells that the other pages are the sub-page of the current page. The following toctree example is build upon the example sturcture.

```{toctree}

getting-started
tasks/index
developer
glossary
```

The example structure of documents.

myproject/
├── docs/
│   ├── index.md
│   ├── getting-started.md
│   ├── developer.md
│   ├── glossary.md
│   └── tasks/
│       ├── index.md
│       └── other pages...

The toctree about other pages in the tasks folder should be indicated in the docs/tasks/index.md.