The `mozbuildsymbols` directive fed its generated reStructuredText back into the
including document with `state_machine.insert_input()`, which MyST does not
implement, so the page could not be converted to Markdown.
Rather than reach into docutils to parse the generated text by hand, drop the
directive and write the page out as Markdown, next to the mots export. Sphinx
then reads it like any other page, which is what keeps the section nesting, the
`mozbuild_subcontext_*` targets and the cross references working. The page is
written to the staging directory rather than to `build/docs`, so nothing is
generated in the source tree.
The docstrings the reference is built from move to Markdown as well: the
indented literal blocks become `python` fenced code blocks, as moz.build is a
Python dialect, the double backtick literals become single backtick code spans,
the `^^^` underlined headings become `####`, and the two `:ref:` roles become
`{ref}`, pointing at the labels the pages they target actually define now (they
had been dangling, which the allowed warnings for `context.py` were hiding).
Docstrings that `sphinx.ext.autodoc` renders as well stay reStructuredText and
are embedded in an `eval-rst` fence, the same way D321834 keeps the Python API
documentation working.
Differential Revision: https://phabricator.services.mozilla.com/D321833
Sylvestre Ledru
63d8c55fcf