VCS Documentation

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 [email protected]: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 [email protected]: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

For VCS Developers

Coming soon!