1654339 - glean_parser should generate Autodocs for FOG

Status: RESOLVED FIXED

(Toolkit :: Telemetry, task, P2)

Description

[Chris H-C :chutten]

glean_parser can output markdown which can be included in the FOG in-tree documentation... if we can find some way to do it.

The current forerunner for doing this properly is to convince Sphinx or mach doc to generate the autodocs as part of the doctree build (the docs schedule in mozbuild). This will ensure they fit nicely into existing workflows and we will always publish the most up-to-date version.

(Though it does mean that autodocs will not be present in the m-c checkout.)

We need to have public and complete documentation before we can check in data collections in-tree (otherwise we'll fail Data Review), so this needs to be done before bug 1651110 can start collecting validation information. (( Or it will have to manually generate the autodocs and check them in temporarily while we figure this out ))

Options that have already been considered and dropped include:

• Having mach build generate the docs in the source dir for inclusion in the m-c source tree.
  • Dropped because mach build does not and should not generate artefacts in the source tree.
• Adding a linter to detect when the docs need to be updated, forcing the user to run the autodocs generation manually when adding/changing metrics.
  • Dropped because of insufficient magic.

Comment 1

[Chris H-C :chutten]

The specific requirements for this are for mach doc to

from glean_parser import translate
translate.translate([Path(x) for x in GLEAN_METRICS_AND_PINGS_FILES], 'markdown', Path('toolkit/components/glean/docs'), {'project_title': 'Firefox Desktop'})

To do this GLEAN_METRICS_AND_PINGS_FILES must be an iterable that mach doc can find. That list (which will be composed of GLEAN_METRICS_FILES and GLEAN_PINGS_FILES which will live in toolkit/components/glean/moz.build) needs to get from fog's moz.build to mach doc somehow. My guess is that we can probably communicate it somehow similar to how SPHINX_TREES does it, but I don't know what magic glue we might have to write in order to make that happen.

My work on this bug is somewhat hampered by my not being able to run mach doc, so I'm gonna unassign this pending bug 1655056's resolution.

Comment 2

[Chris H-C :chutten]

Attachment: Bug 1654339 - Add Glean metrics autodocs to moztreedocs r?janerik!,ahal!

Comment 3

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/def563fc3dea
Add Glean metrics autodocs to moztreedocs r=janerik,ahal

Comment 4

[Cosmin Sabou [:CosminS]]

https://hg.mozilla.org/mozilla-central/rev/def563fc3dea