Sphinx isn’t just for Python¶
I have heard a few times over the past couple months that Sphinx is “mainly for Python projects”. This line of thinking makes sense, because Sphinx was created to document Python itself. Sphinx however, is a generic documentation tool that is capable of documenting any software project.
The goal of Sphinx is to help you write prose documentation. Prose docs work great for any kind of software you are documenting.
What it doesn’t handle particularly well is generation of docs from source code. This is a task that is best left to a language-specific tooling, so I don’t see this as a major downside of Sphinx.
As I run Read the Docs, I get a chance to see a lot of the different things people are doing with Sphinx. At the beginning, Read the Docs was mostly Python projects. These days though, some of our biggest and most active projects are in a number of languages.
I think that actions speak louder than words, so here is a small sample of projects using Sphinx for things that aren’t documenting Python code.
Creating your own language¶
- Bootstrap Datepicker: http://bootstrap-datepicker.readthedocs.org/en/latest/
- CasperJS: http://docs.casperjs.org/en/latest/
- Inventory Tweaks: http://inventory-tweaks.readthedocs.org/en/latest/
- Idiorm: http://idiorm.readthedocs.org/en/latest/
- Little books of R: http://little-books-of-r.readthedocs.org/en/latest/
I hope that this shows you how Sphinx can be used for documentation all kinds of software, not just Python. It is a fantastically powerful documentation tool, and you shouldn’t discard it without looking at it closely.