12.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.

Useful links

The AFNI documentation repository is open source and publicly available here:

https://github.com/afni/afni_doc

Help with sphinx: details directives (lists, tables, inserting figures, etc.)

https://docutils.sourceforge.io/docs/ref/rst/directives.html

Help with sphinx: general reference notes/building:

https://www.sphinx-doc.org/en/master/contents.html

https://www.sphinx-doc.org/en/master/usage/index.html

Sphinx “Cloud” theme docs (this theme is the starting point of documentation, but with an increasing number of style tweaks added on top):

https://cloud-sptheme.readthedocs.io/en/latest/cloud_theme.html

“Hidden code blocks” extension (thanks, A. Scopatz!), which is used occasionally within these docs:

http://scopatz.github.io/hiddencode/#

Prepare to make for Sphinx docs on your 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:

   cd
   git clone https://github.com/afni/afni_doc
   

3. Install necessary dependencies. This can be done with Conda, using an included environment.yml file:

   • Install+setup Conda, e.g., see Miniconda: Python(s) in a convenient setup (note the quick setup section there).

     
     

   • Use the afni_doc’s *.yml file to create an environment with all Python-and Sphinx-related dependencies for building:

     cd ~/afni_doc
     conda env create -f environment.yml
     

   • Activate the environment:

     conda activate sphinxdocs
     

4. Build repo (with optional pre-copy of repo). I prefer not to build in my git repo. Therefore, I first rsync the repo somewhere else and then build. You can do the same or just build in your git repo:

   cd
   rsync -av --exclude=".*" ~/afni_doc/ ~/afni_doc_build
   
   cd ~/afni_doc_build
   
   # build docs, with several "helpers" scripts run first
   tcsh do_doc_build_and_copy.tcsh -build
   

5. View docs. Open the created index.html file with a browser, such as Firefox or let AFNI find one:

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