sphinx-js : autodoc-style extraction into Sphinx for your JS project ¶
Why ? ¶
When you write a JavaScript library, how do you explain it to people? If it’s a small project in a domain your users are familiar with, JSDoc’s alphabetical list of routines might suffice.
But in a larger project, it is useful to intersperse prose with your API docs without having to copy and paste things.
sphinx-js lets you use the industry-leading Sphinx documentation tool with JS projects. It provides a handful of directives, patterned after the Python-centric autodoc ones, for pulling JSDoc-formatted documentation into reStructuredText pages.
And, because you can keep using JSDoc in your code, you remain compatible with the rest of your JS tooling, like Google’s Closure Compiler.
Setup ¶
-
Install JSDoc using npm.
jsdoc
must be on your$PATH
, so you might want to install it globally:npm install -g jsdoc
We’re known to work with jsdoc 3.4.3.
-
Install sphinx-js, which will pull in Sphinx itself as a dependency:
pip install sphinx-js
-
Make a documentation folder in your project by running
sphinx-quickstart
and answering its questions:cd my-project sphinx-quickstart > Root path for the documentation [.]: docs > Separate source and build directories (y/n) [n]: > Name prefix for templates and static dir [_]: > Project name: My Project > Author name(s): Fred Fredson > Project version []: 1.0 > Project release [1.0]: > Project language [en]: > Source file suffix [.rst]: > Name of your master document (without suffix) [index]: > Do you want to use the epub builder (y/n) [n]: > autodoc: automatically insert docstrings from modules (y/n) [n]: > doctest: automatically test code snippets in doctest blocks (y/n) [n]: > intersphinx: link between Sphinx documentation of different projects (y/n) [n]: > todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: > coverage: checks for documentation coverage (y/n) [n]: > imgmath: include math, rendered as PNG or SVG images (y/n) [n]: > mathjax: include math, rendered in the browser by MathJax (y/n) [n]: > ifconfig: conditional inclusion of content based on config values (y/n) [n]: > viewcode: include links to the source code of documented Python objects (y/n) [n]: > githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: > Create Makefile? (y/n) [y]: > Create Windows command file? (y/n) [y]:
-
In the generated Sphinx conf.py file, turn on
sphinx_js
by adding it toextensions
:extensions = ['sphinx_js']
-
If your JS source code is anywhere but at the root of your project, add
js_source_path = '../somewhere/else'
on a line by itself in conf.py. The root of your JS source tree should be where that setting points, relative to the conf.py file. (The default,../
, works well when there is adocs
folder at the root of your project and your source code lives directly inside the root.) -
If you have special jsdoc configuration, add
jsdoc_config_path = '../conf.json'
(for example) to conf.py as well. -
If you’re documenting only JS and no other languages, you can set your « primary domain » to JS in conf.py:
primary_domain = 'js'
Then you can omit all the « js: » prefixes in the directives below.