michael@0: =================================
michael@0: Mozilla Source Tree Documentation
michael@0: =================================
michael@0: 
michael@0: .. toctree::
michael@0:    :maxdepth: 1
michael@0: 
michael@0:    {indexes}
michael@0: 
michael@0: Python Packages
michael@0: ===============
michael@0: 
michael@0: .. toctree::
michael@0:    :maxdepth: 2
michael@0: 
michael@0:    {python_packages}
michael@0: 
michael@0: Managing Documentation
michael@0: ======================
michael@0: 
michael@0: This documentation is generated via the
michael@0: `Sphinx <http://sphinx-doc.org/>`_ tool from sources in the tree.
michael@0: 
michael@0: To build the documentation, run ``mach build-docs``. Run
michael@0: ``mach help build-docs`` to see configurable options.
michael@0: 
michael@0: Adding Documentation
michael@0: --------------------
michael@0: 
michael@0: To add new documentation, define the ``SPHINX_TREES`` and
michael@0: ``SPHINX_PYTHON_PACKAGE_DIRS`` variables in ``moz.build`` files in
michael@0: the tree and documentation will automatically get picked up.
michael@0: 
michael@0: Say you have a directory ``featureX`` you would like to write some
michael@0: documentation for. Here are the steps to create Sphinx documentation
michael@0: for it:
michael@0: 
michael@0: 1. Create a directory for the docs. This is typically ``docs``. e.g.
michael@0:    ``featureX/docs``.
michael@0: 2. Create an ``index.rst`` file in this directory. The ``index.rst`` file
michael@0:    is the root documentation for that section. See ``build/docs/index.rst``
michael@0:    for an example file.
michael@0: 3. In a ``moz.build`` file (typically the one in the parent directory of
michael@0:    the ``docs`` directory), define ``SPHINX_TREES`` to hook up the plumbing.
michael@0:    e.g. ``SPHINX_TREES['featureX'] = 'docs'``. This says *the ``docs``
michael@0:    directory under the current directory should be installed into the
michael@0:    Sphinx documentation tree under ``/featureX``*.
michael@0: 4. If you have Python packages you would like to generate Python API
michael@0:    documentation for, you can use ``SPHINX_PYTHON_PACKAGE_DIRS`` to
michael@0:    declare directories containing Python packages. e.g.
michael@0:    ``SPHINX_PYTHON_PACKAGE_DIRS += ['mozpackage']``.
michael@0: 
michael@0: Indices and tables
michael@0: ==================
michael@0: 
michael@0: * :ref:`genindex`
michael@0: * :ref:`modindex`
michael@0: * :ref:`search`