JS API docs for mozilla-central

[Robert Helmer]

Hello,

As of bug 1389341, we now have a way to automatically generate and
host JS API docs for every mozilla-central push.

We currently do have API docs for many components on MDN, but these
are largely out of date (at least in my experience) and likely to be
culled as MDN re-focuses on web content and away from Mozilla-specific
technologies [1].

Here is a quick example, for the public AddonManager API:
https://firefox-source-docs.mozilla.org/toolkit/mozapps/extensions/addon-manager/AddonManager.html

To use it for your own code:
1) Check that JSDoc generates the output you expect (you may need to
use a @class annotation on object initializer style definitions for
instance[2])
2) Create an .rst file, which may contain explanatory text as well as
the API docs. The minimum will look something like
https://firefox-source-docs.mozilla.org/_sources/toolkit/mozapps/extensions/addon-manager/AddonManager.rst.txt
3) Ensure your component is on the js_source_path here in the sphinx
config: https://hg.mozilla.org/mozilla-central/file/72ee4800d415/tools/docs/conf.py#l46
4) Run `mach doc` locally to generate the output and confirm that it
looks correct

That should be it! The "Doc" taskcluster job will now generate your
API docs, and they will be automatically published on
firefox-source-docs.mozilla.org

Thanks to Erik Rose for writing sphinx-js [3] and helping to integrate
it and gps for standing up the docs and fixing the hosting situation!


-Rob

1 - https://blog.mozilla.org/opendesign/future-mdn-focus-web-docs/

2 - Also note that AddonManager uses the "AddonManager forwards to
AddonManagerInternal" pattern. It was recently discussed here whether
we can stop using this pattern, but in the meantime it's possible to
accommodate it with a combination of @private for private methods and
@lends:
https://hg.mozilla.org/mozilla-central/file/72ee4800d415/toolkit/mozapps/extensions/AddonManager.jsm#l626

3 - https://hacks.mozilla.org/2017/07/introducing-sphinx-js-a-better-way-to-document-large-javascript-projects/
_______________________________________________
firefox-dev mailing list
firef...@mozilla.org
https://mail.mozilla.org/listinfo/firefox-dev

[Kris Maglione]

\o/

Thank you for finally making this happen. I've been wanting to
do this for the code that I work on for years, now...

--
Kris Maglione
Senior Firefox Add-ons Engineer
Mozilla Corporation

There is no greater mistake than the hasty conclusion that opinions
are worthless because they are badly argued.
--Thomas Huxley

[Felipe G]

This is awesome! \o/

I'm actually searching right now for what I could use to generate documentation (to publish on firefox-source-docs) from a JSON schema. Does anyone know if there's already something available that I could look into?

Ideally, I want to:

- write a JSON schema in-tree

- use that schema to validate a JSON file, client-side on Firefox

- use that same file to generate docs about the schema

Any suggestions are welcome!

Cheers,

Felipe

[Gregory Szorc]

On Tue, Nov 21, 2017 at 10:37 AM, Felipe G <fel...@gmail.com> wrote:

This is awesome! \o/

I'm actually searching right now for what I could use to generate documentation (to publish on firefox-source-docs) from a JSON schema. Does anyone know if there's already something available that I could look into?

Ideally, I want to:

- write a JSON schema in-tree

- use that schema to validate a JSON file, client-side on Firefox

- use that same file to generate docs about the schema

Any suggestions are welcome!

The tool we're using (Sphinx) is extensible in many different ways. We already have one custom extension in mozilla-central for auto-generating the moz.build symbols documentation. That lives at https://hg.mozilla.org/mozilla-central/file/72ee4800d415/python/mozbuild/mozbuild/sphinx.py (it is loaded via tools/docs/conf.py). Essentially, that extension registers a "mozbuildsymbols" rst directive that when evaluated is expanded to a bunch of standard rst directives. Sphinx then converts those standard rst directives to HTML, PDF, etc. If you want to generate docs for things like JSON schemas, IDL files, etc, you basically need to write some code that can convert some input to rst. Then you glue that into Sphinx with an extension.

While I'm here, the ability to extend rst [with Sphinx] is one of the big advantages of rst over markdown. The learning curve of rst - especially Sphinx extended rst - is a bit higher. But it is so much more powerful and flexible and enables us to have nice things. We've only scratched the surface of what's possible with our Sphinx docs.

[Tom Prince]

On Tue, Nov 21, 2017 at 11:59 AM Gregory Szorc <g...@mozilla.com> wrote:

On Tue, Nov 21, 2017 at 10:37 AM, Felipe G <fel...@gmail.com> wrote:

This is awesome! \o/

I'm actually searching right now for what I could use to generate documentation (to publish on firefox-source-docs) from a JSON schema. Does anyone know if there's already something available that I could look into?

Ideally, I want to:

- write a JSON schema in-tree

- use that schema to validate a JSON file, client-side on Firefox

- use that same file to generate docs about the schema

Any suggestions are welcome!

The tool we're using (Sphinx) is extensible in many different ways. We already have one custom extension in mozilla-central for auto-generating the moz.build symbols documentation. That lives at https://hg.mozilla.org/mozilla-central/file/72ee4800d415/python/mozbuild/mozbuild/sphinx.py (it is loaded via tools/docs/conf.py). Essentially, that extension registers a "mozbuildsymbols" rst directive that when evaluated is expanded to a bunch of standard rst directives. Sphinx then converts those standard rst directives to HTML, PDF, etc. If you want to generate docs for things like JSON schemas, IDL files, etc, you basically need to write some code that can convert some input to rst. Then you glue that into Sphinx with an extension. 

And there may already exist plugins that do that (https://pypi.python.org/pypi/sphinx-jsonschema which I haven't looked at).

-- Tom