nerdvegas/rez — pull request #67 by mstreatfield (2014-07-01 02:04:59+00:00)
Title: Read the docs

Add the required files to build Rez documentation using Sphinx, and to https://readthedocs.org/.

An example of the built documentation can be found here : http://rez.readthedocs.org/en/latest/

The initial conf.py file was generated by running:

sphinx-quickstart

The initial rst files for the API documentation were generated by running:

sphinx-apidoc --output-dir=api --private ../src/ ../src/rez/vendor ../src/rez/backport/

The docs can be built locally by running:

cd docs
make html

I have hooked the `version` and `release` attributes in `docs/conf.py` up to the `__version__` attribute in `src/rez/__init__.py`.

I have configured a "read the docs" project to host the documentation, however it will need additional configuration once this branch is merged to 2.0, and once 2.0 is merged to master.

Specifically, we will need to:

* add a webhook to the git repository configuration so that when a tag is created the documentation is regenerated.
* configure read the docs to use the nerdvegas repository and master branch.
* add extra maintainers to the read the docs project configuration if you want access to the configuration.

There is an extension for Sphinx called sphinxcontrib-programoutput that would enable us to automatically generate the documentation for the Rez cli based on the documentation strings already provided to argparse. This requires additional configuration of the Rez project to allow it to run inside a virtualenv and so I have not undertaken this for the moment.

This branch was taken from the 2.0 at the beginning of the week as it wasn't clear what the state of the other branches was. I don't think it will introduce conflicts, but might require modifications with respect to the change from `settings` to `config`. `sphinx-apidoc` might also need to be re-run to pick up any new classes etc.