Sphinx documentation

Welcome to The Pencil Code documentation hub! Whether you are here to read, build, or rewrite history one .rst file at a time, this page will guide you through using and contributing to our Sphinx-based documentation system.

Why Sphinx (and not PDFs)?

Personal opinion of the writer — not an official stance of the Pencil Code community (yet).

PDF manuals were great — in 1983, when documentation came on CD-ROMs and printers made that satisfying dot-matrix screech. But this is 2025:

Reasons PDFs no longer cut it:

  • Requires a separate app just to open — assuming your phone didn’t uninstall it to free space for cat videos.

  • You can’t bookmark sections, only pages, and scrolling to “page 146 of 274” isn’t navigation — it’s a pilgrimage.

  • Search only works if the PDF was exported properly — otherwise Ctrl+F is just placebo.

  • You can’t embed GIFs, interactive plots, or collapsible code blocks — unless you print them on paper and wave them around theatrically.

  • Every time you update one sentence, you have to re-export and redistribute the entire file, like it’s a Soviet-era newspaper.

  • Mobile users must pinch-zoom like raccoons rummaging through a garbage can.

  • PDFs don’t do dark mode. They blind you at 2 AM and don’t even apologize.

Reasons Sphinx/ReadTheDocs wins by default:

  • Opens in any browser, even on smart fridges and game consoles running Chromium.

  • Updates instantly — no re-uploading 20 MB files just because a comma moved.

  • URLs link directly to functions, sections, or parameters, not the entire Dead Sea Scrolls.

  • Integrates with copy buttons, syntax highlighting, collapsible content, math rendering, and actually clickable links.

  • Can embed videos, images, Jupyter notebooks, Mermaid diagrams, or whatever wizardry you throw at it.

  • Users can switch instantly between latest, stable, or even historic “oops” versions.

  • Feels like part of the internet — not like downloading a legal document from 1997.

In short: Sphinx + ReadTheDocs = documentation that feels like it belongs in 2025, not the printer era.

Using the documentation

This space is designed to organize all Pencil Code knowledge into a structure that:

  • You can navigate without psychic powers

  • You can search without chanting regex

  • You can read without scrolling through 500 lines of Fortran (and much less intimidating)

The pages you are reading are built with Sphinx, hosted on ReadTheDocs, and generated from two sources:

  • Text documentation — written in reStructuredText (.rst) or Markdown (.md) and rendered into webpages.

  • Autogenerated documentation — extracted from inline comments in the source code and formatted by Sphinx extensions.

Note

Sphinx was born in the Python ecosystem, so it speaks fluent Python. It also speaks okay-ish Fortran with the help of sphinx-fortran — like a tourist using Google Translate.

Note

Sphinx can format your documentation beautifully… But only if you write actual documentation. It’s a renderer, not an AI therapist.

Contributing to the documentation

You can improve:

  • The human-written docs (like this file)

  • The code’s inline documentation, which feeds into the autodoc system

The documentation source lives in the main Pencil Code GitHub repository.

To contribute:

  1. Clone the repository — instructions are in Download the Pencil Code

  2. Navigate to the documentation folder:

    $ cd pencil-code/doc/readthedocs

  3. Edit the .rst files

  4. Commit and push your changes

ReadTheDocs will automatically rebuild the documentation — like magic, but with CI.

Compiling the documentation locally

Best practice: build the documentation locally before committing, so you don’t accidentally break the website and summon angry developers.

There are two ways to build locally:

  • Use Docker (guaranteed to work, unless the universe is against you)

  • Use Sphinx directly (fast if you already have all the dependencies)

Using the Docker Builder

This project includes a preconfigured Docker environment built specifically for compiling the Pencil Code documentation. No guessing versions, no hunting for obscure Fortran bindings — everything is already installed inside the container.

Requirements

Docker must be installed on your system. See Installation.

How to run - full/slow

Navigate to:

~/pencil-code/doc/readthedocs/documentation-docker

Then run:

make

This will build and use a Docker container to generate the full Sphinx documentation into:

~/pencil-code/doc/readthedocs/_build/html/

The first run builds the full environment — dependencies, images, and possibly your patience — so grab a coffee.

Subsequent runs are fast and only rebuild modified files.

Note

This command generates the html of all the rst files and the automatic documentation for all Python and Fortran modules. It currently takes around 20 minutes.

How to run - fast

If you already have a complete documentation build and only need to test updates to text files, you don’t need to rebuild all the autodoc output.

Fast build — ignores autogenerated code docs (useful when you’re editing prose, not APIs):

make fast

Fast enough that you can’t leave your desk for coffee. It’s usually up and running in about one minute.

Output goes to _build/html.

Using Sphinx Directly

If you already have Python tooling installed, you can build the docs directly.

  1. Make sure pip is installed.

  2. Install these required Python packages (e.g. via pip3):

    sphinx
sphinx-autoapi
sphinxcontrib.images
sphinx-rtd-theme
rstcloth
six
latexcodec
bibtexparser
pybtex
sphinxcontrib.bibtex
matplotlib

  3. Build the documentation as follows:

    git pull --rebase    # make sure your local copy is fresh
make html            # full build

    This builds everything, including autogenerated Python and Fortran code documentation.

The first build takes a few minutes. Subsequent builds are much faster.

Output appears in _build/html.

If Sphinx refuses to install or errors out in mysterious ways, don’t panic — blame dependency hell, and use the Docker setup provided in this repository.

Fast build

The same “fast” target works for direct builds too:

make fast

When you only need to rebuild text changes, this keeps your workflow snappy and your CPU fans calm.