1Overview
2========
3
4We use the Sphinx <http://www.sphinx-doc.org> documentation system to document mobly APIs.
5
6It works by using certain "source" files that define how to build the documentation in the target format (e.g. HTML, PDF, text, etc.).
7
8To use the sphinx system locally, you need to have sphinx installed. See the sphinx project site for installation details.
9
10
11Initial Generation of Sphinx source files
12=========================================
13
14The initial sphinx autogeneration of mobly APIs were performed by running in root dir of the project:
15
16sphinx-apidoc mobly --full -o docs -H 'Mobly'
17
18This created the full sphinx project in the 'docs' directory and generated the source files pointing to the mobly package and its contents.
19
20
21Updating Documentation
22======================
23
24readthedocs.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.
25
26If 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.
27
28Subsequent runs of sphinx-apidoc can be run with:
29
30sphinx-apidoc mobly -o docs -H 'Mobly'
31
32
33Building the Target documents
34=============================
35
36To generate the documentation in HTML format, run from within the docs directory:
37
38make html
39
40That will generate the documentation in the _build directory.
41