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 introductio

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.