JS API docs for mozilla-central

Felipe G felipc at gmail.com
Tue Nov 21 18:37:26 UTC 2017


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


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/
> 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
> 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/9cbe7b98/attachment-0001.html>


More information about the firefox-dev mailing list