Sphinx as a Documentation Tool

This is created using a documentation generation tool written in python known as Sphinx.

If you are a regular python user, and would like to use Sphinx, install it using the package management procedure with which you are most comfortable.

Installing Conda

If you are novice python user, here are instructions for installing Sphinx using the package manager known as Conda (short for Anaconda) on Mac OSX.

Open a terminal window and execute these three commands:

  1. Download the installation script:

$ curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh

  1. Modify the execution permissions of the recently downloaded script:

$ chmod 755 ./Miniconda3-latest-MacOSX-x86_64.sh

  1. Run the installation script and follow its instructions:

$ ./Miniconda3-latest-MacOSX-x86_64.sh

Downloading Sphinx

Now that Conda is installed, use it to download Sphinx. Close and reopen the terminal window to ensure conda is activated.

  1. Invoke Conda and instruct it to install two packages, Sphinx and the “Read the Docs” CSS theme for Sphinx:

$ conda install sphinx sphinx-rtd-theme

Clone the Repository

You’re ready to clone the repository:

$ git clone https://github.com/AetherModel/AetherDocumentation.git
$ cd AetherDocumentation

Edit Files and Remake the Documentation

The files that comprise the documentation are written in reStructuredText which offers a reasonably simple syntax for writing documentation while still accommodating the elements needed for technical writing such as equations, references, code snippets, tables, etc.

Find the reStructuredText documents contained in this repository:

find . -name "*.rst"

Edit them using your favorite text editor and then remake the documentation:

make clean
make html

View the remade documentation in your favorite web browser by opening the ./_build/html/index.html using your graphical user interface or via the command line:

open ./_build/html/index.html