Introduction to Sphinx for Picasso v3.0 Documentation

[ZPYin]

Download Sphinx

Start Anaconda command line by typing windows key and search anaconda. And enter the commands below inside Anaconda command line.

# create a conda environment for building Sphinx documentation
conda create -n test_sphinx   # test_sphinx is the name of the conda environment. Or other name that you would prefer.

# activate the conda environment
conda activate test_sphinx

# install python
conda install python==3.6

# install sphinx
pip install sphinx 

# install some sphinx dependencies
pip install recommonmark sphinx_rtd_theme sphinxcontrib-matlabdomain

Some details of Sphinx installation can be found here.

Edit Sphinx documentation

The source code of Sphinx documentation is located under ./doc-auto/source, where all editable ReStructureText (.rst) files were stored. This is the place where you can edit the documentation.

I recommend to read the .rst file syntax before your first try. Tutorial can be found here.

Nice tool for learning Sphinx syntax: https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/Index.html

Build Sphinx documentation

After your editing, you can build the .rst files into HTML pages (or other file format) for beautiful layout.

sphinx-build -b html /path/to/doc-auto/source /path/to/docs

While building the Sphinx documentation, you can see build report in the command line. You need to resolve all errors for successful build. After the build, you can find the HTML pages under the folder of ./docs. You can just open the HTLM pages for a quick look.

Push changes to the GitHub repository

git add auto-doc docs
git commit -m "commit message"
git push origin master

Related topics

• automated api level html documentation #89
• homogenize profile output #117