Skip to content

VCS Documentation

Jump to bottom
Edward Brown edited this page Jan 11, 2017 · 14 revisions

For VCS Users

NOTE: current version of VCS documentation is in "beta" stage!

This means that there are possibly code examples that don't work, and functions that are documented which are either deprecated or currently not implemented.

System setup

If you don't have conda, get conda.

Run the following at the command line, with $ENV_NAME replaced by an environment name of your choosing:

   $ conda create -n $ENV_NAME -c uvcdat -c conda-forge uvcdat=2.8.0
   $ source activate $ENV_NAME

Install Sphinx and the ReadThedocs theme in your new environment:

  $ conda install sphinx sphinx_rtd_theme

Building the latest "beta" documentation

We're considering the current state of the documentation in the VCS master branch to be in a "beta" state. This is because we are in the process of fully updating the documentation, but we're not quite there yet.

To start, clone the master branch into a location of your choosing:

$ git clone https://github.com:UV-CDAT/vcs.git $PATH_TO_DIR

Then navigate to the docs folder, and use the Makefile there to build the documentation webpage:

$ cd PATH_TO_DIR/docs
$ make html

When you run $ make html, there are some formatting errors in the master branch of the documentation that cause warnings to show up in angry red letters (thus the "beta" label).

After it is done building:

$ open _build/html/index.html

Viola! The current state of VCS's documentation. There's a nice little introduction guide to VCS for beginning users. If you just want API documentation, there's a link on the side that will take you to that. There's also a search bar in case you want to look at a specific class/function/module.

Building the latest "alpha" documentation

This documentation is currently under development. There are many more examples, and many less errors when running it through Sphinx. It's more complete than the "beta" documentation, but is not yet at a point where we have integrated it into the master branch.

To start, clone this repo into a location of your choosing:

$ git clone https://github.com/embrown/vcs.git $PATH_TO_DIR

Then, checkout the branch that has the most recent documentation updates:

$ cd $PATH_TO_DIR
$ git checkout more_more_documentation

Make sure your conda environment is activated. I recommend setting up a new environment for the "alpha" documentation.

Install the current vcs source from the more_more_documentation branch into your conda environment:

$ python setup.py install --old-and-unmanageable

Then navigate to the docs folder, and use the Makefile there to build the documentation webpage:

$ cd docs/
$ make html

After it is done building:

$ open _build/html/index.html

Building the PDF manual

Setup remains the same as above, but you also have to install TeX on your machine so that sphinx can use it to build the PDF.

After that's done, in the docs directory, type:

$ make latexpdf

If TeX installed correctly, sphinx should start building the pdf for you.

It's going to scream at you about a bunch of formatting errors. Ignore those, and when it gets to the line:

   ! LaTeX Error: Too deeply nested.

   See the LaTeX manual or LaTeX Companion for explanation.
   Type  H <return>  for immediate help.
   ...                                              
                                                  
   l.5784 \item {} \begin{description}
                                   
   ?

Type R at the console and hit Enter

Because LaTeX is insane, repeat that process one more time. If you don't the PDF output tends to be screwy (missing chapters, broken links, and other badness).

Viola! You have a PDF.

For VCS Developers

NOTE: The following section discusses changes not yet merged into VCS master as of 1/5/2017. It is intended as a guide for future VCS developers, after those changes have been merged. Please remove this notification once the changes have been merged.

I'll assume that you already have your conda environment set up, and that you know the general process for installing your local changes. If not, read this.

What to document?

VCS's documentation is in RST format so we can use Sphinx and host our docs on readthedocs.

If you add a new feature (class, function, etc.) please add an RST-formatted docstring describing its parameters and what it does, along with an example section with a doctest.

Likewise, if you change an existing feature so much that the API changes (parameters change data type, return value changes, etc.), please update the docstring(s) of the affected function(s)/class(es).

If you need more information on how to do any of these, please refer to the Documenting UVCDAT wiki, and/or the official Sphinx documentation.

Using doctests

Note: This section contains out-dated information. VCS will soon switch to running doctests as part of its tests suite

doctest_vcs.py is no longer being used in vcs.

For information on writing doctests and doctest formatting, refer to Documenting UVCDAT's doctests section. In VCS, since we can't reliably use Sphinx to run doctests, we wrote doctest_vcs to allow us to do so.

To run doctest_vcs on all modules, you can simply navigate to docs/doctest_info/scripts and type:

$ ./run_all_doctests.sh

NOTE: Check to make sure the file has executable permissions on your system if this does not work.

This will run the tests and generate a report with the full doctest output in docs/doctest_info/reports, and a markdown-formatted summary containing any errors encountered, as well as a list of places where doctests are missing. The list of functions/classes missing doctests acts as a pretty good measuring stick for determining how well-documented the module is.

To run doctests on an individual module, navigate to docs/doctest_info/scripts and type:

$ python doctest_vcs $MODULE_NAME

This will output the most basic form of doctest feedback to the terminal.

To run doctests and generate reporting as is done in run_all_doctests:

$ python doctest_vcs -v -r $MODULE_NAME > ../reports/$MODULE_NAME.report
$ python doctest_vcs -v --LO $MODULE_NAME```

This is done in two steps because the doctest module creates its own version of python stdout internally, so it is hard to change where the output is going.

The easiest way to view the doctest results is in docs/doctest_info after you push the changed reports to the repo. There is a README.md that has a link to each module's markdown-formatted log. You can also just open up the markdown file in a text editor, if you don't want to push to the repo yet.

doctest_vcs.py options

-v, --verbose : Acts as a verbose flag when running a module through doctest.testmod. This gives more detailed output that includes every doctest that is run, any errors encountered, and a report of missing doctests at the end.

-r, --report : Flag to report a summary when the tests finish.

-p, --package : Use this to provide a package name. The default is vcs.

-a, --all : If set, doctest will report all failures for an individual test. Otherwise, doctest will only report the first failure.

-l, --log : Log the doctest errors and missing doctests in a .md file.

--LO : ONLY run the logging function. Assumes that a .report exists for the module name provided.

-i, --ignore : Takes a list of regular expressions that will be used to ignore certain function signatures when parsing report output for missing doctests.

--ifile : Same as ignore, but parses a file containing newline-delimited regular expressions

Troubleshooting

Sometimes the build process fails for one reason or another, or changes that have been made to the documentation don't get reflected in the output. When this happens, here are a few steps to take before assuming the world is on fire and nothing makes sense:

  • Make sure you're using the right virtual environment.

  • Make sure your virtual environment has sphinx and sphinx_rtd_theme installed (conda list with your virtual environment active)

  • Install VCS in your virtual environment. Every time you make changes to your local version of VCS, you have to: $ cd $PATH_TO_VCS; python setup.py install --old-and-unmanageable within your virtual environment to apply the changes.

  • Try removing the _build directory and running sphinx again. When sphinx builds output for the first time, it creates _build/doctrees, which tells it how to construct the output. If this directory exists when you run make html or make latexpdf, sphinx will use it to construct the output, even if something in VCS has changed. Removing _build/ before you run make will ensure that sphinx builds the doctree for the most up-to-date version in your environment.

Other useful things

If you're maintaining/updating VCS's documentation on a regular basis, there are some things that I have in ~/.bash_aliases that may be of use to you:

alias vcsdocs='cd $PATH_TO_YOUR_VCS/docs/' : just gets you there quicker

alias vcs='cd $PATH_TO_YOUR_VCS' : same

alias reinstall='vcs;python setup.py clean; rm -rf build; python setup.py install --old-and-unmanageable': use this with your conda environment activated to update your virtual environment with the latest changes you have made to the documentation

alias rehtml='vcsdocs; rm -rf _build/html _build/doctrees; make html; open _build/html/index.html;' : build and view the documentation webpage

alias repdf='vcsdocs; rm -rf _build/latex _build/doctrees; make latexpdf; make latexpdf; open _build/latex/vcs.pdf;' : build and view the documentation pdf (complete with the extra call to make latexpdf because LaTeX makes no sense)

Clone this wiki locally