16.5.1. Setup for building sphinx

Writing: In progress

This page describes the process of building the AFNI documentation on your local machine, as well as on the server to push to The World. This can be done on Linux and Mac systems.

The majority of the AFNI online documentation website (which you are reading right now...) is written using Sphinx. As part of the standard build process, some “helper” scripts are run, as well, which are mainly written in Python. For example, these scripts parse all current helpfiles in the AFNI binaries directory and make them available here. NB: For a full docs build, it is assumed that you have AFNI correctly installed on your system.

Prepare to make Sphinx documentation on local OS

  1. Install AFNI on your system. The directory of AFNI binaries can be located anywhere on your system: the Sphinx docs use a which afni in the conf.py file to find it. If you haven’t already installed AFNI, see default installation instructions for various OSs here.

  2. Download the afni_docs repo. You can clone the git repo, for example to your home directory:

    git clone https://github.com/afni/afni_doc
  3. Install necessary dependencies. This can be done with Conda, using an included environment.yml file:

    You can set this environment as default, or just switch to it when you want to build the Sphinx documentation.

Make Sphinx documentation on local OS

  1. Activate the necessary Conda environment:

    conda activate sphinxdocs
  2. (optional, but recommended) Copy repo files outside git directory. I prefer not to build in my git repo. Therefore, I first rsync the repo (without the git stuff) somewhere else, before building:

    rsync -av --exclude=".*" ~/afni_doc/ ~/afni_doc_build
    cd ~/afni_doc_build
  3. Build docs. There is a do_* script for building the documentation, including running several “helper” scripts (mostly Python). You can choose to build the SUMA docs from scratch (which will open+drive SUMA a bit), though most documentation building doesn’t need that. There are also options for pushing the docs to The World, but that is typically only done on the server:

    tcsh do_doc_build_and_copy.tcsh -build
  4. View docs. Open the created index.html file with a specific browser, such as Firefox, or let AFNI choose one:

    firefox _build/html/index.html
    afni_open -b _build/html/index.html