• file
• revisions
• annotate
• diff
• comparison
• raw

tools/docs/index.rst@b8a032363ba2 (annotated)

tools/docs/index.rst

Thu, 22 Jan 2015 13:21:57 +0100

author

Michael Schloh von Bennewitz <michael@schloh.com>

date

Thu, 22 Jan 2015 13:21:57 +0100

branch

TOR_BUG_9701

changeset 15

b8a032363ba2

permissions

-rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

michael@0	1	=================================
michael@0	2	Mozilla Source Tree Documentation
michael@0	3	=================================
michael@0	4
michael@0	5	.. toctree::
michael@0	6	:maxdepth: 1
michael@0	7
michael@0	8	{indexes}
michael@0	9
michael@0	10	Python Packages
michael@0	11	===============
michael@0	12
michael@0	13	.. toctree::
michael@0	14	:maxdepth: 2
michael@0	15
michael@0	16	{python_packages}
michael@0	17
michael@0	18	Managing Documentation
michael@0	19	======================
michael@0	20
michael@0	21	This documentation is generated via the
michael@0	22	`Sphinx <http://sphinx-doc.org/>`_ tool from sources in the tree.
michael@0	23
michael@0	24	To build the documentation, run ``mach build-docs``. Run
michael@0	25	``mach help build-docs`` to see configurable options.
michael@0	26
michael@0	27	Adding Documentation
michael@0	28	--------------------
michael@0	29
michael@0	30	To add new documentation, define the ``SPHINX_TREES`` and
michael@0	31	``SPHINX_PYTHON_PACKAGE_DIRS`` variables in ``moz.build`` files in
michael@0	32	the tree and documentation will automatically get picked up.
michael@0	33
michael@0	34	Say you have a directory ``featureX`` you would like to write some
michael@0	35	documentation for. Here are the steps to create Sphinx documentation
michael@0	36	for it:
michael@0	37
michael@0	38	1. Create a directory for the docs. This is typically ``docs``. e.g.
michael@0	39	``featureX/docs``.
michael@0	40	2. Create an ``index.rst`` file in this directory. The ``index.rst`` file
michael@0	41	is the root documentation for that section. See ``build/docs/index.rst``
michael@0	42	for an example file.
michael@0	43	3. In a ``moz.build`` file (typically the one in the parent directory of
michael@0	44	the ``docs`` directory), define ``SPHINX_TREES`` to hook up the plumbing.
michael@0	45	e.g. ``SPHINX_TREES['featureX'] = 'docs'``. This says *the ``docs``
michael@0	46	directory under the current directory should be installed into the
michael@0	47	Sphinx documentation tree under ``/featureX``*.
michael@0	48	4. If you have Python packages you would like to generate Python API
michael@0	49	documentation for, you can use ``SPHINX_PYTHON_PACKAGE_DIRS`` to
michael@0	50	declare directories containing Python packages. e.g.
michael@0	51	``SPHINX_PYTHON_PACKAGE_DIRS += ['mozpackage']``.
michael@0	52
michael@0	53	Indices and tables
michael@0	54	==================
michael@0	55
michael@0	56	* :ref:`genindex`
michael@0	57	* :ref:`modindex`
michael@0	58	* :ref:`search`