Bug 1817289: generate exported mots in mach doc r=sheehan,firefox-source-docs-reviewers,sylvestre

- generate exported index.rst file in mach doc
- stop tracking docs/mots/index.rst, add it to ignore files
- add mots.yaml to sphinx-docs sparse profile
- add mots to requirements

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

.gitignore

@@ -208,3 +208,6 @@ tools/esmify/jscodeshift
 tools/esmify/jscodeshift.cmd
 tools/esmify/jscodeshift.ps1
 tools/esmify/package-lock.json
+
+# Ignore automatically generated mots documentation
+docs/mots/index.rst

.hgignore

@@ -290,3 +290,6 @@ gfx/wr/target/
 ^extensions/spellcheck/locales/en-US/hunspell/dictionary-sources/scowl
 ^extensions/spellcheck/locales/en-US/hunspell/dictionary-sources/support_files/
 ^extensions/spellcheck/locales/en-US/hunspell/dictionary-sources/*en_US-mozilla*
+
+# Ignore automatically generated mots documentation
+^docs/mots/index.rst

build/sparse-profiles/sphinx-docs

@@ -43,3 +43,6 @@ glob:**/package*.json
 
 # Read to set the version of the docs.
 path:config/milestone.txt
+
+# mots configuration
+path:mots.yaml

python/mozbuild/mozbuild/sphinx.py

@@ -3,9 +3,13 @@
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
 import importlib
+from pathlib import Path
 
 from docutils import nodes
 from docutils.parsers.rst import Directive
+from mots.config import FileConfig
+from mots.directory import Directory
+from mots.export import export_to_format
 from sphinx.util.docstrings import prepare_docstring
 from sphinx.util.docutils import ReferenceRole
 
@@ -174,6 +178,30 @@ def format_module(m):
     return lines
 
 
+def export_mots(app):
+    """Load mots configuration and export it to file."""
+    # Load from disk and initialize configuration and directory.
+    base_path = Path(app.srcdir).parent
+    config = FileConfig(base_path / "mots.yaml")
+    config.load()
+    directory = Directory(config)
+    directory.load()
+
+    # Fetch file format (i.e., "rst") and export path.
+    frmt = config.config["export"]["format"]
+    path = base_path / config.config["export"]["path"]
+
+    # Generate output.
+    output = export_to_format(directory, frmt)
+
+    # Create export directory if it does not exist.
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Write changes to disk.
+    with path.open("w", encoding="utf-8") as f:
+        f.write(output)
+
+
 class MozbuildSymbols(Directive):
     """Directive to insert mozbuild sandbox symbol information."""
 
@@ -248,5 +276,9 @@ def setup(app):
     #
     # Here, we invoke our custom code for staging/generating all our
     # documentation.
+
+    # Export and write "governance" documentation to disk.
+    export_mots(app)
+
     manager.generate_docs(app)
     app.srcdir = manager.staging_dir

python/sites/docs.txt

@@ -18,6 +18,7 @@ pypi:livereload==2.6.3
 pypi:Markdown==3.4.3
 pypi:MarkupSafe==2.0.1
 pypi:mock==5.0.1
+pypi:mots==0.8.0
 pypi:myst-parser==1.0
 pypi:mdit-py-plugins==0.3.5
 pypi:parsimonious==0.10.0

tools/lint/codespell.yml

@@ -66,7 +66,6 @@ codespell:
         - devtools/docs/contributor/tools/storage/
         - tools/lint/cpp/mingw-headers.txt
         - tools/lint/test/test_codespell.py
-        - docs/mots/index.rst
         - "**/package-lock.json"
     # List of extensions coming from:
     # tools/lint/{flake8,eslint}.yml