Setup documentation (from scratch)

Note

If everything is already set up, simply run this script to build the documentation locally and verify your changes before committing them.

bash build_doc.sh

To be done only once.

1. First steps

1.1. Create your dev environment

conda create -n traceratops_dev python=3.11
conda activate traceratops_dev
pip install sphinx

1.2. Generate the “docs” folder structure

mkdir docs
cd docs
sphinx-quickstart

The last command ask you few question:

> Separate source and build directories: YES
> Project name:
> Author name(s):
> Project release []: 0.0.1

It create few files:

.
├── build (empty folder, used when you generate doc)
├── make.bat (don't modify, it's used to build doc)
├── Makefile (don't modify, it's used to build doc)
└── source (folder that you will fill with doc pages)
    ├── conf.py (the place to configure your doc)
    ├── index.rst (main doc page)
    ├── _static	(put your static data here, like picture)
    └── _templates (unused?)

1.3. Build locally your doc

  • cd docs/

  • sphinx-build -b html source/ build/html

1.4. Open your doc inside a web navigator

firefox build/html/index.html

2. generate documentation from code

3. Tips

  • Think to delete content of build folder, this can solve strange bug…

    You can use a bash script to build:

#!/bin/bash

rm -r docs/build/html
sphinx-build -b html docs/source docs/build/html

  • If you have bug with image display, may be you can refresh cache on your web navigator.

  • Custom the design with html_theme variable inside conf.py

    • For ReadTheDocs theme:

      • pip install sphinx-rtd-theme

      • html_theme = "sphinx_rtd_theme"

  • On ReadTheDocs you can customise the branch used to build the doc:

    • readthedocs.org > dashboard > “your_project” > Settings > Default branch

4. Deploy on ReadTheDocs

  1. Create an account on https://readthedocs.org/

  2. On ReadTheDcos, connect with github:

  • Settings > Account > Connected services > Add new connection

  1. On GitHub (Your personal account) give access for readthedocs:

  • Profil > Settings > (Integrations) > Applications > Authorized OAuth Apps > Read the Docs Community (readthedocs.org)

  • You should see a list intitle “Organization access”, clic on “Grant” button of the organization that host your repository.

  1. On GitHub (code repository) configure your project for readthedocs:

  • On the default branch (main or master for old repo)

  • add a .readthedocs.yaml file at the root folder

# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the version of Python and other tools you might need
build:
  os: ubuntu-24.04
  tools:
    python: "3.11"

# Build documentation in the docs/ directory with Sphinx
sphinx:
  builder: html
  configuration: docs/source/conf.py

# Optionally declare the Python requirements required to build your docs
python:
  install:
  - requirements: docs/requirements.txt
  - method: pip
    path: .

  1. Add inside docs folder, a requirements.txt file with only the dependencies used to build doc:

sphinx
numpydoc
sphinx-rtd-theme
myst-parser
sphinx-argparse

  1. inside the doc conf.py file, mock the code dependencies:

If you generate documentation via sphinx-apidoc or sphinx-argparse, the code will be compiled in order to extract the useful information for the doc in the code. The mock system, thanks to the autodoc_mock_imports variable, allows you to ignore external import instructions in the code when building the documentation.

#...
import os
import sys

autodoc_mock_imports = [
    "numpy",
    "matplotlib",
    "pandas",
    "astropy",
    "tqdm",
]

sys.path.insert(0, os.path.abspath("../../traceratops/"))
#...

  1. Go back to your ReadTheDocs dashboard:

  • “Add project”

  • Follow instruction, use “Configure manually” if your repo isn’t find automatically.