
Introducing sphinx-js, a better way to document large JavaScript projects - nachtigall
https://hacks.mozilla.org/2017/07/introducing-sphinx-js-a-better-way-to-document-large-javascript-projects/
======
maga
I use jsdoc2md[1] and Gitbook[2], with a plugin[3] to integrate the two. An
example of docs automatically generated from JSDoc comments:
[https://scriptare.gitbooks.io/compago/](https://scriptare.gitbooks.io/compago/)

[1][https://github.com/jsdoc2md/jsdoc-to-
markdown](https://github.com/jsdoc2md/jsdoc-to-markdown)

[2][https://www.gitbook.com/](https://www.gitbook.com/)

[3][https://github.com/zandaqo/dmd-plugin-
gitbook](https://github.com/zandaqo/dmd-plugin-gitbook)

------
abritinthebay
I’ve long held that there are two types of documentation.

\- One, like this and JSDoc, is structured documenting of the code interface.
It’s a reference tool.

\- Two, is a more free form documenting of _intent_. Commented source code
tools like Docco serve this well.

Both are useful in different situations and don’t replace each other. For 3rd
party tools the former is more useful, for internal - the latter.

Unfortunately the parsers for each are usually mutually incompatible and I
really wish there was a tool that supported both.

~~~
grincho
That's what I've always liked about Sphinx: you can get reference docs
extracted from source code, but you can also surround them with more in-depth
introduction or explanation.

For example, these are the reference docs to a package I used to maintain:
[http://django-
tidings.readthedocs.io/en/latest/reference.htm...](http://django-
tidings.readthedocs.io/en/latest/reference.html). They're entirely extracted
from the source.

However, most of the other pages in that manual are written expressly for new
users, organized to teach. The magic of Sphinx is that those introductory
pages can link effortlessly back into the reference docs. There are many
examples on [http://django-
tidings.readthedocs.io/en/latest/introduction....](http://django-
tidings.readthedocs.io/en/latest/introduction.html).

And it doesn't stop at linking; you can also embed extracted docs into the
midst of a contextualized explanation. See
[https://mozilla.github.io/fathom/optimization.html](https://mozilla.github.io/fathom/optimization.html),
which is JS code and so uses sphinx-js.

I missed all that power from the Python world; that's why I ported some of it
to the nascent JS ecosystem.

~~~
abritinthebay
It's certainly good at being descriptive but it's still very focused on the
reference style interface.

Which is _fine_ of course, but it doesn't really help with the latter case as
anything other than a secondary concern. That's _great_ when your primary
usage is as a reference but suffers the same problem as JSDoc/etc when it
isn't.

But it's a _better_ form of what it's doing, for sure.

~~~
kevin_thibedeau
You can write a book with ReST. Nobody's going to do that with Javadoc. The
documentation generation features are all bolt-ons and not in any way central
to how Sphinx works.

------
wdfx
I think it is unfair that the article says there is only one other contender.

There exists for example esdoc [1] which is capable of compiling together
written documents with generated documentation. I've just implemented this for
two work projects with the return of many thanks from my team.

That said I will also check out sphinx-js because we also maintain python
projects and already use sphinx for those.

[1] [https://github.com/esdoc/esdoc](https://github.com/esdoc/esdoc)

~~~
grincho
Author here. I just learned about esdoc this morning; thanks for mentioning
it! But it doesn't appear to be much of an improvement over JSDoc for my
purposes, as you still get little control over the organization of your
content. It is alphabetical reference docs plus a few predefined bolt-on pages
([https://esdoc.org/#integration-manual](https://esdoc.org/#integration-
manual)):

    
    
        Overview
        Design
        Installation
        Usage
        Tutorial
        Configuration
        Example
        Advanced
        FAQ
        Changelog
    

You can't add more. And, as far as I can tell (the documentation I can find is
silent on the point), those pages are islands, with no ability to call content
out of the code. (I'd love to be shown wrong. Did you find otherwise?)
However, I do applaud esdoc's better support for more modern JS features!

~~~
wdfx
Some of your assumptions are incorrect. Those names you list are documentation
categories, under which you can publish any pages in your own order. The final
docs do not actually display those category names, but some have different
menu colours by default.

You can also link between written docs and API docs, though it is a bit
manual/hacky (you need to know the rendered file paths).

~~~
grincho
Thanks for clearing that up!

------
wry_discontent
I have yet to see anything that actually documents well other than code
itself. Comments are _always_ subject to the problem of going stale or being
poorly worded. I haven't played with it much, but Clojure's spec looks like a
good tool for documenting how functions should behave. That plus a description
in the docstring might be the best thing out there right now.

~~~
ch4s3
Have you seen Elixir's doctests[1]? They're docs with a code example that gets
run by your tests, and if the example doesn't work, your tests fail.

[1][https://elixir-lang.org/getting-started/mix-otp/docs-
tests-a...](https://elixir-lang.org/getting-started/mix-otp/docs-tests-and-
with.html#doctests)

~~~
forsaken
Python also has a similar concept:
[https://docs.python.org/2/library/doctest.html](https://docs.python.org/2/library/doctest.html)

Sphinx also has additional doc testing methods that let you test the code
examples in your actual docs: [http://www.sphinx-
doc.org/en/stable/ext/doctest.html](http://www.sphinx-
doc.org/en/stable/ext/doctest.html)

~~~
sjellis
I was surprised (and pleased) to find out that Rust has doctests as well.

