docs/README.sphinx

Overview
========

We use the Sphinx <http://www.sphinx-doc.org> documentation system to document mobly APIs.

It works by using certain "source" files that define how to build the documentation in the target format (e.g. HTML, PDF, text, etc.).

To use the sphinx system locally, you need to have sphinx installed. See the sphinx project site for installation details.


Initial Generation of Sphinx source files
=========================================

The initial sphinx autogeneration of mobly APIs were performed by running in root dir of the project:

sphinx-apidoc mobly --full -o docs -H 'Mobly'

This created the full sphinx project in the 'docs' directory and generated the source files pointing to the mobly package and its contents.


Updating Documentation
======================

readthedocs.org hosts Sphinx documentation for a number of open source projects. If the appropriate github hook is set, it will autogenerate documentation with each submission.

If there are significant changes to the mobly package (adding a new module), you will need to run sphinx-apidoc again to update the sphinx source files for the new package. Or, you can add the necessary files/directives to the sphinx source files manually.

Subsequent runs of sphinx-apidoc can be run with:

sphinx-apidoc mobly -o docs -H 'Mobly'


Building the Target documents
=============================

To generate the documentation in HTML format, run from within the docs directory:

make html

That will generate the documentation in the _build directory.