Auto generate API docs

[kewisch]

It would be useful if we can generate API docs on github pages for the APIs we have in this repo, this way we have a good overview of what is supported in the latest version.

[jobisoft]

This would overlap with my project to rewrite our Phython schema-to-markdown-to-readthedocs script as a node script. I cannot say however when I get to it, but would be interested to collaborate in efforts in that direction.

[kewisch]

Yeah, I was betting you have something in store. Where does the python script live? We could run that in a GH action as well.

[jobisoft]

The automatic source-to-doc process is running since a few months, but it depends on a couple of assumptions, which are only valid inside a Mozilla source tree. Running the script on the stand-alone calendar json files does not work. There is an intermediate step to produce annotated schema files:

https://github.com/thunderbird/webext-annotated-schemas-generator/blob/main/README.md

But if I place the files in the source tree and run the process, it kinda works:

Not sure how much we can re-use it for the pure Experiment documentation.

[jobisoft]

Thought about this a bit more. If we want to have generated docs for this API based on the tools I have developed for MZLA, we could do the following:

• fork https://github.com/thunderbird/webext-docs-generator
• modify it and remove all dependencies on the mozilla tree, and work with the schema files directly, instead of using annotated schema files:
  • no differentiation between MV2 and MV3
  • no revision checking (no compat data)
  • no extended annotations

We use annotations for core APIs, to overcome limitations in the schema format. In order to generate nice documentation, we need additional fields. Not sure if it is worth the effort to make that available for Experiment API documentation.

If we move this forward, the process should create documentation for all APIs listed in this repository, and not only for the calendar API?