| JS API docs for mozilla-central | Robert Helmer | 11/21/17 10:16 AM | 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 |
| Re: API docs for JS in mozilla-central | Kris Maglione | 11/21/17 10:21 AM | \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 |
| Re: JS API docs for mozilla-central | Felipe G | 11/21/17 10:37 AM | 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 |
| Re: JS API docs for mozilla-central | Gregory Szorc | 11/21/17 10:59 AM | On Tue, Nov 21, 2017 at 10:37 AM, Felipe G <fel...@gmail.com> wrote: 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. |
| Re: JS API docs for mozilla-central | Tom Prince | 11/21/17 3:31 PM |
And there may already exist plugins that do that (https://pypi.python.org/pypi/sphinx-jsonschema which I haven't looked at). -- Tom |