-
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 this.
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].
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.
report output for missing doctests.```
```--ifile : Same as ignore, but parses a file containing newline-delimited regular expressions```
<!--
DEV NOTE
References contain links to a branch on a forked
VCS repo (https://github.com/embrown/vcs/blob/more_more_documentation/).
Once the more_more_documentation branch is merged, please update these links to point to VCS's master branch.
-->
<!-- vcs fork refs -->
[doctest_vcs]: https://github.com/embrown/vcs/blob/more_more_documentation/docs/doctest_info/scripts/doctest_vcs.py
[docs/doctest_info]: https://github.com/embrown/vcs/blob/more_more_documentation/docs/doctest_info/
[docs/doctest_info/scripts]: https://github.com/embrown/vcs/blob/more_more_documentation/docs/doctest_info/scripts/
[docs/doctest_info/reports]: https://github.com/embrown/vcs/blob/more_more_documentation/docs/doctest_info/reports/
[markdown]: https://github.com/embrown/vcs/blob/more_more_documentation/docs/doctest_info/markdown/
[run_all_doctests]: https://github.com/embrown/vcs/blob/more_more_documentation/docs/doctest_info/scripts/run_all_doctests.sh
<!-- other refs -->
[Documenting UVCDAT]: https://github.com/UV-CDAT/uvcdat/wiki/Documenting-UVCDAT
[doctests]: https://github.com/UV-CDAT/uvcdat/wiki/Documenting-UVCDAT#doctests
[doctest.testmod]: https://docs.python.org/2.7/library/doctest.html#doctest.testmod
[readthedocs]: https://readthedocs.org/
[Sphinx documentation]: http://www.sphinx-doc.org/en/1.5.1/