JS API docs for mozilla-central

Gregory Szorc gps at mozilla.com
Tue Nov 21 18:58:36 UTC 2017


On Tue, Nov 21, 2017 at 10:37 AM, Felipe G <felipc at 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.


>
>
> On Tue, Nov 21, 2017 at 4:16 PM, Robert Helmer <rhelmer at mozilla.com>
> wrote:
>
>> 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/exte
>> nsions/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/moz
>> apps/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
>> firefox-dev at mozilla.org
>> https://mail.mozilla.org/listinfo/firefox-dev
>>
>
>
> _______________________________________________
> firefox-dev mailing list
> firefox-dev at mozilla.org
> https://mail.mozilla.org/listinfo/firefox-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.mozilla.org/pipermail/firefox-dev/attachments/20171121/094d6e92/attachment.html>


More information about the firefox-dev mailing list