1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/tools/docs/index.rst Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,58 @@
1.4 +=================================
1.5 +Mozilla Source Tree Documentation
1.6 +=================================
1.7 +
1.8 +.. toctree::
1.9 + :maxdepth: 1
1.10 +
1.11 + {indexes}
1.12 +
1.13 +Python Packages
1.14 +===============
1.15 +
1.16 +.. toctree::
1.17 + :maxdepth: 2
1.18 +
1.19 + {python_packages}
1.20 +
1.21 +Managing Documentation
1.22 +======================
1.23 +
1.24 +This documentation is generated via the
1.25 +`Sphinx <http://sphinx-doc.org/>`_ tool from sources in the tree.
1.26 +
1.27 +To build the documentation, run ``mach build-docs``. Run
1.28 +``mach help build-docs`` to see configurable options.
1.29 +
1.30 +Adding Documentation
1.31 +--------------------
1.32 +
1.33 +To add new documentation, define the ``SPHINX_TREES`` and
1.34 +``SPHINX_PYTHON_PACKAGE_DIRS`` variables in ``moz.build`` files in
1.35 +the tree and documentation will automatically get picked up.
1.36 +
1.37 +Say you have a directory ``featureX`` you would like to write some
1.38 +documentation for. Here are the steps to create Sphinx documentation
1.39 +for it:
1.40 +
1.41 +1. Create a directory for the docs. This is typically ``docs``. e.g.
1.42 + ``featureX/docs``.
1.43 +2. Create an ``index.rst`` file in this directory. The ``index.rst`` file
1.44 + is the root documentation for that section. See ``build/docs/index.rst``
1.45 + for an example file.
1.46 +3. In a ``moz.build`` file (typically the one in the parent directory of
1.47 + the ``docs`` directory), define ``SPHINX_TREES`` to hook up the plumbing.
1.48 + e.g. ``SPHINX_TREES['featureX'] = 'docs'``. This says *the ``docs``
1.49 + directory under the current directory should be installed into the
1.50 + Sphinx documentation tree under ``/featureX``*.
1.51 +4. If you have Python packages you would like to generate Python API
1.52 + documentation for, you can use ``SPHINX_PYTHON_PACKAGE_DIRS`` to
1.53 + declare directories containing Python packages. e.g.
1.54 + ``SPHINX_PYTHON_PACKAGE_DIRS += ['mozpackage']``.
1.55 +
1.56 +Indices and tables
1.57 +==================
1.58 +
1.59 +* :ref:`genindex`
1.60 +* :ref:`modindex`
1.61 +* :ref:`search`
