Brief guild to get started with sphinx and readthedocs.io

README.md

You are in the right place if you...

1. Want to write documents and docstrings for a Python module and turn them into a presentable form.
2. Build and host your doc on readthedocs.io (if you don't mind open source your code on github.com) ...
   Or build and host your doc on your own.

Project structure

This is a recommended way to organize your code (e.g. if you have a module named my_mod)

my_mod-pkg/ (base dir for Git, etc.)
 |--- README.md
 |--- my_mod/
       |--- __init__.py
       |--- whatever.py
 |--- docs/

Get started

Now we assume that you are at base dir my_mod-pkg/ and you don't have my_mod-pkg/docs created yet.

pip install sphinx sphinx_rtd_theme # or conda install ... 
bash init-doc.sh

Run this only once, and enter your project information as prompted.

Write the doc

Now you can start writing document pages in my_mod-pkg/docs/source using reStructuredText format. Don't worry if you have never work with it before. You can learn how people are doing it by browsing the docs/ dir in existing Python projects.

When your are ready, on my_mod-pkg/docs/ do:

pip install -r requirements.txt
make html

If it builds successfully, you can pull up a simple Python HTTP server to view the generated document locally:

python -m http.server 8080
# Open your browser, go to localhost:8080

Host it on readthedocs.io

You need an account for that and link your GitHub repo.

Additionally, it takes a config file my_mod-pkg/.readthedocs.yml, e.g.:

version: 2

python:
  version: 3.8
  install:
    - requirements: docs/requirements.txt

init-doc.sh

echo docs/build/ >> .gitignore
mkdir docs
cd docs
sphinx-quickstart --sep --release '' --language en
sed -i 's/# import os/import os/g' source/conf.py
sed -i 's/# import sys/import sys/g' source/conf.py
sed -i "s/# sys.path.insert(0.*/sys.path.insert(0, os.path.abspath('..\/..'))/g" source/conf.py

sed -i "/General configuration/a \
 \
master_doc = 'index'\
" source/conf.py

sed -i '/^# ones.$/a \
import sphinx_rtd_theme' source/conf.py

sed -i '/^extensions = \[$/a \
    "sphinx.ext.autodoc",\
    "sphinx.ext.napoleon",\
    "sphinx_rtd_theme",\
    "sphinxcontrib_trio",' source/conf.py

sed -i 's/html_theme =.*/html_theme = "sphinx_rtd_theme"/g' source/conf.py

cat >> source/conf.py <<EOF 

html_css_files = [
    'css/custom.css',
]

def setup(app):
    app.add_css_file("css/custom.css")
EOF

mkdir source/_static/css
cat > source/_static/css/custom.css <<EOF
/* Get rid of the horrible red for literal content */
.rst-content tt.literal, .rst-content tt.literal, .rst-content code.literal {
    color: #222 !important;
}
EOF

cat > requirements.txt <<EOF
sphinx
sphinx_rtd_theme
EOF
echo "In 'requirements.txt', include all packages required to build your doc"