.. _sphinx: ********************* 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 :ref:`download` 2. Navigate to the documentation folder: .. code:: bash $ 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) .. _sphinx-docker: 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 :ref:`docker-installation`. How to run - full/slow ^^^^^^^^^^^^^^^^^^^^^^^ Navigate to: ``~/pencil-code/doc/readthedocs/documentation-docker`` Then run: .. code:: bash 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): .. code:: bash 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. #. Make sure ``pip`` is installed. #. Install these required Python packages (e.g. via ``pip3``):: sphinx sphinx-autoapi sphinxcontrib.images sphinx-rtd-theme rstcloth six #. Build the documentation as follows: .. code:: bash 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 :ref:`Docker setup ` provided in this repository. Fast build ^^^^^^^^^^ The same “fast” target works for direct builds too: .. code:: bash make fast When you only need to rebuild text changes, this keeps your workflow snappy and your CPU fans calm.