13.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.
Install AFNI on your system. The directory of AFNI binaries can be located anywhere on your system: the Sphinx docs use a
which afniin the
conf.pyfile to find it. If you haven’t already installed AFNI, see default installation instructions for various OSs here.
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
Install necessary dependencies. This can be done with Conda, using an included
Use the afni_doc’s
*.ymlfile to create an environment with all Python-and Sphinx-related dependencies for building:
cd ~/afni_doc conda env create -f environment.yml
You can set this environment as default, or just switch to it when you want to build the Sphinx documentation.
Activate the necessary Conda environment:
conda activate sphinxdocs
(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:
cd rsync -av --exclude=".*" ~/afni_doc/ ~/afni_doc_build cd ~/afni_doc_build
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
View docs. Open the created
index.htmlfile with a specific browser, such as Firefox, or let AFNI choose one:
firefox _build/html/index.html afni_open -b _build/html/index.html