Introducing sphinx-js: autodoc for JavaScript

[er...@mozilla.com]

In case anyone else is working on nontrivial JS projects, I wanted to let you know about sphinx-js, something I cooked up to scratch my own itch while working on Fathom. 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

[mgi...@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

[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