1. Why Sphinx and for which users ?ΒΆ
Sphinx requires to learn a language called ReST or RST that stands for restructured Text. To get an idea of the syntax, click on the show Source link in the right side bar, in any page.
The advantage of the ReST syntax resides in its human-readable nature, which makes it useful to include inside your source code (e.g. docstrings in Python). Taking notes in ReST language is also conveninent since it remains readable but can be also interpreted later into nice layout (pdf, html, ...).
ReST and Sphinx provides a rich syntax made of directives. Sphinx comes with many of them in addition to standard ones provided by the ReST language. For instance, you can include LaTeX code for your equations. Yet, there are many directives and extensions, and it is sometimes difficult to figure out their names and options so it may not be for everybody. However, if you are developer, and especially a Python developer, the investment worths it !!!
These pages give you the elements to start a documentation using Sphinx and provides a summary of directive/options gathered in the ReST tutorial section.
Note
I should mention that the Sphinx official page is very well done and improves all the time. I encourage you to go and visit their website of course ! Thanks to the Sphinx developers