Mozilla brings Python-style project documentation to JavaScript

Wanting a more full-featured documentation tool for large JavaScript projects, Mozilla has unveiled Sphinx-js, a plug-in that pulls JSDoc-formatted JavaScript documentation into the Sphinx documentation tool used in the Python world.  

Sphinx-js consumes documents and tags from the JSDoc markup language used to document JavaScript APIs and libraries. Sphinx-js delegates the parsing to JSDoc itself. The Sphinx tool, meanwhile, is used to initialize a docs folder in the root folder of your project, whereupon the plug-in is activated and you document your code using the reStructuredText plain text markup syntax and parser system.

“When it comes time to call in some extracted documentation, you use one of Sphinx-js’s special directives, modeled after the Python-centric autodoc’s mature example,” Mozilla’s Erik Rose said. Documentation stays compatible with JavaScript tooling.

Developers can add long examples that reside in reStructuredText files and comprise a manual. Sphinx-js also features a directive for classes, either from ECMAScript 2015 or functions-as-directors. The tool can optionally iterate over class members, documenting along the way. Order can be controlled as well. References are supported for same-named JavaScript entities that might collide otherwise.

The Sphinx-js plugin is freely downloadable from the Python Package Index. Sphinx-js was born out of a desire for JavaScript documentation tooling beyond what JSDoc supports. Rose said JSDoc has had benefits including well-defined tags to describe common structures and tooling like Closure Compiler to hook into those tags. Still, the output is just an alphabetical list of what is in a project. Functions are flattened, leaving new users to infer relationships and sort them. This might work for tiny libraries but does not work for large libraries such as the Fathom framework.