4 ms·

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.

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 9y ago
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.html http://django-tidings.readthedocs.io/en/latest/reference.htm.... 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.html http://django-tidings.readthedocs.io/en/latest/introduction..... 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 9y ago
  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 9y ago
    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.
carussell 9y ago
JSDoc has @fileoverview, but it seems to be rarely (or insufficiently) used, in favor of overdocumenting functions and parameters. On the other hand, I find that I use @fileoverview far more often. Treat it as a way to explain not the tree in front of you, but where it fits into the overall forest. Here's a comment of mine from a while ago describing how Mozilla's old "Bonsai" tool worked: https://news.ycombinator.com/item?id=11381815 https://news.ycombinator.com/item?id=11381815

grincho 9y ago

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.html http://django-tidings.readthedocs.io/en/latest/reference.htm.... 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.html http://django-tidings.readthedocs.io/en/latest/introduction..... 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 9y ago
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 9y ago
  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.

carussell 9y ago

JSDoc has @fileoverview, but it seems to be rarely (or insufficiently) used, in favor of overdocumenting functions and parameters. On the other hand, I find that I use @fileoverview far more often. Treat it as a way to explain not the tree in front of you, but where it fits into the overall forest. Here's a comment of mine from a while ago describing how Mozilla's old "Bonsai" tool worked: https://news.ycombinator.com/item?id=11381815 https://news.ycombinator.com/item?id=11381815