Bug 1594925 - Create a documentation section in the doc r=ahal

Differential Revision: https://phabricator.services.mozilla.com/D52273

--HG--
extra : moz-landing-system : lando

tools/docs/config.yml

@@ -18,6 +18,7 @@ categories:
         - tools/try
         - build/buildsystem
         - taskcluster
+        - tools/docs
     testing_doc:
         - testing/marionette
         - testing/geckodriver

tools/docs/docs/adding-documentation.rst

@@ -0,0 +1,27 @@
+Adding Documentation
+--------------------
+
+To add new documentation, define the ``SPHINX_TREES`` and
+``SPHINX_PYTHON_PACKAGE_DIRS`` variables in ``moz.build`` files in
+the tree and documentation will automatically get picked up.
+
+Say you have a directory ``featureX`` you would like to write some
+documentation for. Here are the steps to create Sphinx documentation
+for it:
+
+1. Create a directory for the docs. This is typically ``docs``. e.g.
+   ``featureX/docs``.
+2. Create an ``index.rst`` file in this directory. The ``index.rst`` file
+   is the root documentation for that section. See ``build/docs/index.rst``
+   for an example file.
+3. In a ``moz.build`` file (typically the one in the parent directory of
+   the ``docs`` directory), define ``SPHINX_TREES`` to hook up the plumbing.
+   e.g. ``SPHINX_TREES['featureX'] = 'docs'``. This says *the ``docs``
+   directory under the current directory should be installed into the
+   Sphinx documentation tree under ``/featureX``*.
+4. If you have Python packages you would like to generate Python API
+   documentation for, you can use ``SPHINX_PYTHON_PACKAGE_DIRS`` to
+   declare directories containing Python packages. e.g.
+   ``SPHINX_PYTHON_PACKAGE_DIRS += ['mozpackage']``.
+5. In ``tools/docs/config.yml``, defines in which category the doc
+   should go.

tools/docs/docs/index.rst

@@ -0,0 +1,18 @@
+Managing Documentation
+======================
+
+This documentation is generated via the
+`Sphinx <http://sphinx-doc.org/>`_ tool from sources in the tree.
+
+To build the documentation, run ``mach doc``. Run
+``mach help doc`` to see configurable options.
+
+MDN should not be used for Firefox/Gecko processes or source code
+documentation.
+
+.. toctree::
+  :caption: Documentation
+  :maxdepth: 2
+  :glob:
+
+  *

tools/docs/index.rst

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

tools/moz.build

@@ -65,6 +65,8 @@ with Files('compare-locales/docs/**'):
 
 SPHINX_TREES['try'] = 'tryselect/docs'
 
+SPHINX_TREES['docs'] = 'docs/docs'
+
 with Files('tryselect/docs/**'):
     SCHEDULES.exclusive = ['docs']