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