15.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
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
browse from there on.
15.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.
Also a breeze as in this example:
And a few more pictures together:
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.
Once you have something you’re pleased with, send us a note, along with an archive of the directory you have created.
This should be written to instruct how one can send a pull request to github for this.