-
Notifications
You must be signed in to change notification settings - Fork 66
VCS Documentation
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.
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
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.
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
NOTE: The following section discusses changes not yet merged into VCS master as of 12/28/2016. 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
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. 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.
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.
-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.