Introducing sphinx-js: autodoc for JavaScript

[e***@mozilla.com]

In case anyone else is working on nontrivial JS projects, I wanted to let
you know about sphinx-js <https://pypi.python.org/pypi/sphinx-js/>,
something I cooked up to scratch my own itch while working on Fathom
<http://mozilla.github.io/fathom/intro.html>. I was unsatisfied with the
state of JS documentation tools, and I wanted to actually *explain* my
project to people, not just throw an alphabetical list of classes and
routines at them and say "Here, you figure it out!"

Basically, you keep on documenting using the popular JSDoc spellings, and
sphinx-js lets you call JS functions and such into your docs,
autodoc-style. It all happens at normal Sphinx build time; there are no
extra scripts to run or includes to deal with. All you have to do is make
sure jsdoc itself is around, as I delegate to it for the doc extraction.
This gives us the bonus of supporting future syntax changes as well as all
the current JSDoc menagerie, like @private, @class, @lends, etc.

I just finished writing up a detailed intro:
https://hacks.mozilla.org/2017/07/introducing-sphinx-js-a-better-way-to-document-large-javascript-projects/.
Feedback and patches are welcome!

Happy documenting,
Erik Rose
Mad Scientist
Mozilla

[m***@antmicro.com]

Hello Eric,

That's great news - and an excellent contribution.

What I'm actually thinking looking at the Sphinx quickstart quesitons is
that Sphinx should encourage documenting other languages by asking what
language you will be primarily documenting (of course, can by Python by
default, but you could answer 'js' and have it set as default for you).

Based on your answer, the quickstart could ask you to include sphinx-js
instead of autodoc. And indeed, probably it would make sense to name the
package autodoc-js and ship it with Sphinx. That could up the adoption of
your great addition to Sphinxland and increase its visibility.\

I'm wondering what the maintainers think. From what I know Sphinx has
always suffered a bit from the misconception that it's a tool to document
Python projects only. With sphinx-js, it actually has quite some potential
to expand into a new area.

Best regards,
Michael

Post by e***@mozilla.com
In case anyone else is working on nontrivial JS projects, I wanted to let
you know about sphinx-js <https://pypi.python.org/pypi/sphinx-js/>,
something I cooked up to scratch my own itch while working on Fathom
<http://mozilla.github.io/fathom/intro.html>. I was unsatisfied with the
state of JS documentation tools, and I wanted to actually *explain* my
project to people, not just throw an alphabetical list of classes and
routines at them and say "Here, you figure it out!"
Basically, you keep on documenting using the popular JSDoc spellings, and
sphinx-js lets you call JS functions and such into your docs,
autodoc-style. It all happens at normal Sphinx build time; there are no
extra scripts to run or includes to deal with. All you have to do is make
sure jsdoc itself is around, as I delegate to it for the doc extraction.
This gives us the bonus of supporting future syntax changes as well as all
https://hacks.mozilla.org/2017/07/introducing-sphinx-js-a-better-way-to-document-large-javascript-projects/.
Feedback and patches are welcome!
Happy documenting,
Erik Rose
Mad Scientist
Mozilla

[Erik Rose]

Sphinx should encourage documenting other languages by asking what language you will be primarily documenting (of course, can by Python by default, but you could answer 'js' and have it set as default for you). Based on your answer, the quickstart could ask you to include sphinx-js instead of autodoc.

That's a good notion. It's one small question which opens up Sphinx to many new users.

And indeed, probably it would make sense to name the package autodoc-js and ship it with Sphinx. That could up the adoption of your great addition to Sphinxland and increase its visibility.

I'm open to the idea if the maintainers are interested. Also, "sphinx-js" was a terrible naming choice which collides with several other things, so renaming is fine as well.

I'm wondering what the maintainers think.

Maintainers, what do you think? :-)

Cheers,
Erik
Machine Ambassador
Mozilla