Documentation¶
Use Sphinx
Use reStructuredText
Don’t use Markdown (see this for motivation)
Setup¶
cd <project>
python3 -m venv venv
. venv/bin/activate
pip install sphinx sphinx-rtd-theme
mkdir docs
cd docs
sphinx-quickstart
Edit docs/conf.py:
import sphinx_rtd_theme
extensions = [
"sphinx_rtd_theme",
]
html_theme = 'sphinx_rtd_theme'
Build¶
<project>/venv/bin/sphinx-build -b html <project>/docs <project>/docs/_build/html
To enable Live Edit in WebStorm setup a
File Watcher using the above command and
run Debug on the generated html file in <project>/docs/html/ for whichever file you’re working on.
Deploy¶
Push to a public repo and host on Read the Docs.