The DART documentation is maintained using a tool known as Sphinx. Sphinx takes text files, written using the reStructuredText specification, and constructs a set of HTML documentation including a table of contents for all of the files.

Previewing the Sphinx-created documentation locally

Certain text editors such as Atom and Visual Studio Code provide extensions to preview the documentation generated by Sphinx within their text windows. I have had difficulty using these preview capabilities. The following instructions allow you to install Sphinx and build the documentation files on your own computer.

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.

If you aren't a regular python user, this guide provides two sets of installation instructions, the first using python's own pip package manager or the second using the Conda package management system. Pick whichever one you're more comfortable with.

Installation method 1 of 2: using pip

Open a terminal window and execute this command:

$ pip install sphinx sphinx_rtd_theme

Installation method 2 of 2: installing and using 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.

Download the Conda installation script

Open a terminal window and execute these three commands.

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

Modify the execution permissions of the recently downloaded script:

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

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.

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

After you've installed Sphinx, clone the repository

You're ready to clone the repository:

$ git clone https://github.com/NCAR/DART.git

$ cd DART

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 save them. To remake the documentation, place this Makefile in the DART directory:

Makefile

Then rebuild the documentation using:

(If you are using conda you'll need to activate your environment.)

$ conda activate
$ make clean
$ make html

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

$ open ./_build/html/README.html


  • No labels