<div dir="ltr"><div>This is awesome! \o/ <br></div><div><br></div><div>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?</div><div><br></div><div>Ideally, I want to:</div><div><br></div><div>- write a JSON schema in-tree</div><div>- use that schema to validate a JSON file, client-side on Firefox</div><div>- use that same file to generate docs about the schema</div><div><br></div><div><br></div><div>Any suggestions are welcome!</div><div><br></div><div>Cheers,</div><div>Felipe<br></div><div><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Nov 21, 2017 at 4:16 PM, Robert Helmer <span dir="ltr"><<a href="mailto:rhelmer@mozilla.com" target="_blank">rhelmer@mozilla.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hello,<br>
<br>
As of bug 1389341, we now have a way to automatically generate and<br>
host JS API docs for every mozilla-central push.<br>
<br>
We currently do have API docs for many components on MDN, but these<br>
are largely out of date (at least in my experience) and likely to be<br>
culled as MDN re-focuses on web content and away from Mozilla-specific<br>
technologies [1].<br>
<br>
Here is a quick example, for the public AddonManager API:<br>
<a href="https://firefox-source-docs.mozilla.org/toolkit/mozapps/extensions/addon-manager/AddonManager.html" rel="noreferrer" target="_blank">https://firefox-source-docs.<wbr>mozilla.org/toolkit/mozapps/<wbr>extensions/addon-manager/<wbr>AddonManager.html</a><br>
<br>
To use it for your own code:<br>
1) Check that JSDoc generates the output you expect (you may need to<br>
use a @class annotation on object initializer style definitions for<br>
instance[2])<br>
2) Create an .rst file, which may contain explanatory text as well as<br>
the API docs. The minimum will look something like<br>
<a href="https://firefox-source-docs.mozilla.org/_sources/toolkit/mozapps/extensions/addon-manager/AddonManager.rst.txt" rel="noreferrer" target="_blank">https://firefox-source-docs.<wbr>mozilla.org/_sources/toolkit/<wbr>mozapps/extensions/addon-<wbr>manager/AddonManager.rst.txt</a><br>
3) Ensure your component is on the js_source_path here in the sphinx<br>
config: <a href="https://hg.mozilla.org/mozilla-central/file/72ee4800d415/tools/docs/conf.py#l46" rel="noreferrer" target="_blank">https://hg.mozilla.org/<wbr>mozilla-central/file/<wbr>72ee4800d415/tools/docs/conf.<wbr>py#l46</a><br>
4) Run `mach doc` locally to generate the output and confirm that it<br>
looks correct<br>
<br>
That should be it! The "Doc" taskcluster job will now generate your<br>
API docs, and they will be automatically published on<br>
<a href="http://firefox-source-docs.mozilla.org" rel="noreferrer" target="_blank">firefox-source-docs.mozilla.<wbr>org</a><br>
<br>
Thanks to Erik Rose for writing sphinx-js [3] and helping to integrate<br>
it and gps for standing up the docs and fixing the hosting situation!<br>
<br>
<br>
-Rob<br>
<br>
1 - <a href="https://blog.mozilla.org/opendesign/future-mdn-focus-web-docs/" rel="noreferrer" target="_blank">https://blog.mozilla.org/<wbr>opendesign/future-mdn-focus-<wbr>web-docs/</a><br>
<br>
2 -  Also note that AddonManager uses the "AddonManager forwards to<br>
AddonManagerInternal" pattern. It was recently discussed here whether<br>
we can stop using this pattern, but in the meantime it's possible to<br>
accommodate it with a combination of @private for private methods and<br>
@lends:<br>
<a href="https://hg.mozilla.org/mozilla-central/file/72ee4800d415/toolkit/mozapps/extensions/AddonManager.jsm#l626" rel="noreferrer" target="_blank">https://hg.mozilla.org/<wbr>mozilla-central/file/<wbr>72ee4800d415/toolkit/mozapps/<wbr>extensions/AddonManager.jsm#<wbr>l626</a><br>
<br>
3 - <a href="https://hacks.mozilla.org/2017/07/introducing-sphinx-js-a-better-way-to-document-large-javascript-projects/" rel="noreferrer" target="_blank">https://hacks.mozilla.org/<wbr>2017/07/introducing-sphinx-js-<wbr>a-better-way-to-document-<wbr>large-javascript-projects/</a><br>
______________________________<wbr>_________________<br>
firefox-dev mailing list<br>
<a href="mailto:firefox-dev@mozilla.org">firefox-dev@mozilla.org</a><br>
<a href="https://mail.mozilla.org/listinfo/firefox-dev" rel="noreferrer" target="_blank">https://mail.mozilla.org/<wbr>listinfo/firefox-dev</a><br>
</blockquote></div><br></div>