Documentation architecture
==========================

The documentation relies on Sphinx and many Sphinx extensions.

The documentation code is in two main directories:

* :searchfox:`docs`
* :searchfox:`tools/moztreedocs`

Our documentation supports both rst & markdown syntaxes.

Configuration
-------------

The main configuration file is:

:searchfox:`docs/config.yml`

It contains the categories, the redirects, the warnings and others configuration aspects.

The dependencies are listed in:

:searchfox:`tools/moztreedocs/requirements.in`

Be aware that Python libraries stored in `third_party/python` are used in priority (not always for good reasons). See :ref:`Vendor the source of the Python package in-tree <python-vendor>` for more details.


Architecture
------------


:searchfox:`mach_commands <tools/moztreedocs/mach_commands.py>`
contains:

* `mach doc` arguments managements
* Detection/configuration of the environment (nodejs for jsdoc, pip for dependencies, etc)
* Symlink the doc sources (.rst & .md) from the source tree into the staging directory
* Fails the build if any critical warnings have been identified
* Starts the sphinx build (and serve it if the option is set)
* Manages telemetry

:searchfox:`docs/conf.py` defines:

* The list of extensions
* JS source paths
* Various sphinx configuration

At the end of the build documentation process, files will be uploaded to a CDN:

:searchfox:`tools/moztreedocs/upload.py`