<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Tue, Nov 21, 2017 at 10:37 AM, Felipe G <span dir="ltr"><<a href="mailto:felipc@gmail.com" target="_blank">felipc@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><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></blockquote><div><br></div><div>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 <a href="https://hg.mozilla.org/mozilla-central/file/72ee4800d415/python/mozbuild/mozbuild/sphinx.py">https://hg.mozilla.org/mozilla-central/file/72ee4800d415/python/mozbuild/mozbuild/sphinx.py</a> (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.</div><div><br></div><div>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.<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div><br></div></div><div class="gmail-HOEnZb"><div class="gmail-h5"><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:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);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.mo<wbr>zilla.org/toolkit/mozapps/exte<wbr>nsions/addon-manager/AddonMana<wbr>ger.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.mo<wbr>zilla.org/_sources/toolkit/moz<wbr>apps/extensions/addon-manager/<wbr>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/mozilla<wbr>-central/file/72ee4800d415/<wbr>tools/docs/conf.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.or<wbr>g</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/opend<wbr>esign/future-mdn-focus-web-<wbr>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/mozilla<wbr>-central/file/72ee4800d415/<wbr>toolkit/mozapps/extensions/<wbr>AddonManager.jsm#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/2017<wbr>/07/introducing-sphinx-js-a-<wbr>better-way-to-document-large-<wbr>javascript-projects/</a><br>
______________________________<wbr>_________________<br>
firefox-dev mailing list<br>
<a href="mailto:firefox-dev@mozilla.org" target="_blank">firefox-dev@mozilla.org</a><br>
<a href="https://mail.mozilla.org/listinfo/firefox-dev" rel="noreferrer" target="_blank">https://mail.mozilla.org/listi<wbr>nfo/firefox-dev</a><br>
</blockquote></div><br></div>
</div></div><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>
<br></blockquote></div><br></div></div>