16.6. Contribute Your Own Docs

If you feel moved to document a particular aspect of AFNI consider writing one in the SPHINX format and send it to us. The process should be relatively simple:

cd AFNI/doc/SphinxDocs/tutorials
tcsh @gen_all
mkdir -p UserDocs/media
touch UserDocs/UserDocs.rst

Todo

Include instructions for how to get needed material from github

All your images would go in directory media/ and all your documentation can go into UserDocs.rst. Once you have something in there, add a line in index.rst that parallels the line for ContributeDocs.rst then from the command line:

cd AFNI/doc/SphinxDocs
make html

For this to work, you will want to have Latex, Sphinx installed, along with fulltoc. An easy way to install the Sphinx components would be with:

sudo easy_install -U Sphinx
pip install sphinxcontrib-fulltoc

After the build is finished, open _build/html/index.html and browse from there on.

16.6.1. Rst & Sphinx Syntax:

There are plenty of Sphinx tutorials, two important resources are the RST primer and the Sphinx markup construct. You might just want to start by copying this very file and start modifying it.

Some Syntax Examples:

Here is how we reference a tag in this document tree. This takes you back to the beginning of this page, and this next one takes you to some other reference elsewhere in this documentation. Use the handy Show Source link towards the bottom of the left sidebar to find reference tags among other things.

You can also reference terms like 1D from the glossary easily.

Adding figures:

Also a breeze as in this example:

../../_images/suma_mni_n27.jpg

A random picture here.. Note how name is used to create a permalink for the figure which would be accessible from the browser using the link established with ‘ref’. Name does not have to be identical to the image file name, but it is a convenient way to do it.

And a few more pictures together:

../../_images/suma_mni_n27_pry1.jpg

Left aligned! Click on picture to see it in full size. If you’re reading the source, the target path is to the image file as copied by the make html process. Images are copied automatically to _build/html/_images/ so you need not make a copy but you have to set the relative path. (link)

../../_images/suma_mni_n27_pry2.jpg

Right aligned!

../../_images/suma_mni_n27_pry3.jpg

Center of course. Note that in the source I add the center figure last. If I define it between the left and right figures, then the spacing gets messed up…

../../_images/blank1.jpg

Note

The Preceding block:

.. container:: clearer
.. image:: media/blank.jpg

is just a trick to keep upcoming text from wrapping around the figures. And that here was a demonstration of how to insert a note.

Parting note:

Once you have something you’re pleased with, send us a note, along with an archive of the directory you have created.

Todo

This should be written to instruct how one can send a pull request to github for this.