Originally, Sphinx was conceived for a single project, the documentation of the Python language. [...] Since Sphinx has become somewhat popular, interest developed in using it for many different purposes: C/C++ projects, JavaScript, [...].
The sphinx-contrib repository contains more domains available as extensions; currently Ada, CoffeeScript, Erlang, HTTP, Lasso, MATLAB, PHP, and Ruby domains. Also available are domains for Chapel, Common Lisp, dqn, Go, Jinja, Operation, and Scala.
The Python documentation was originally maintained in LaTeX. The fact that Sphinx was designed to replace that shows to this day.
Itâs a beautiful tool for writing manuals, but itâs quite inferior when evaluated as a tool for API documentation. For example:
The autodoc functionality for Python is primitive at best and, if you want anything more automatic than manually maintaining a correspondence between your code and a set of automodule directives, you need to resort to external scripting. (I canât count the number of Python projects where this forced me to read the source to understand something for lack of proper API docs.)
If youâre using the âgather TODO notesâ functionality and you forget to automodule something, the TODO notes from that module will be silently omitted from the docs.
Thatâs not to say it couldnât be used well for Rust⌠itâd just have to be used as a backend with something new to reliably and helpfully inspect the code and output ReST files for Sphinx to process.
In the end, Sphinx and reStructuredText are emerging as the future of Linux kernel documentation, with far more ambitious goals than the original AsciiDoc support patches ever had. [..]
"Honestly, in the end I think we could make either tool do what is needed of it. However, my impression after trying to do a document that needs to have nice publishable output with both tools is that Sphinx is easier to work with, simpler to extend, better supported." In the end, Jonathan's verdict was to go with Sphinx. The patches have been merged, and the first Sphinx-based documentation will appear in the 4.8 kernel. (Jul. 2016)
If Markdown then please use Pandoc Markdown, to at least get basic quoting abilities. With original markdown and many variants one cannot even properly quote (academic standards) a source. It is not possible to do document internal links properly at any place one wants either. Only headings are linkable or external documents. What about sizes of images? Usually not definable in most Markdown variants either.
Markdown is simply way to little power for proper documentation.
Thatâs why I wrote my academic thesis in ReST instead of Markdown. A proper thesis in Markdown (not Pandoc Markdown) is unthinkable. A documentation for a programming language should at least be on par with academic standards for theses.
Markdown is surely insufficient for academic writing. But code documentation shouldnât be a full-blown academic paper. It should explain the peculiarities of the annotated code while been easy to write and maintain. If required you can still create more complex documentation with an external tool and link to that in the code documentation.
There are only really two ReST features which I consistently miss in Markdown:
An intentionally extensible syntax to avoid the need to keep dropping into raw HTML or raw URLs for things like definition lists and apidoc cross-reference markup.
Footnote markup which automatically hyperlinks in both directions.
The former is what I miss in rustdoc and the latter is why I prefer ReST over Markdown everywhere else. (The latter doesnât really fit with rustdocâs templates though)
That said, Iâve been dragging my heels on migrating from the unmaintained, Python 2.x-only ePyDoc when documenting my Python projects because API documentation support in Sphinx is an afterthought. It began as a replacement for the way the CPython 2.x manual used LaTeX and, to this day, its API documentation support hasnât grown out of that âassume the user has the discipline to maintain good documentation using LaTeXâ mindset.
(eg. I see a ton of Sphinx documentation where I have to consult the source code because they neglected to add new auto... directives as the codebase grew or they allowed some of the documentation to fall out of sync in a way rustdoc or a JavaDoc-style tool would never allow. Likewise, ePyDoc will recurse for you so an @todo canât be accidentally omitted from your index the way Sphinxâs equivalent can if you forget an automodule directive.)
(If I can find the time, my plan is to write and submit a plugin that satisfies my needs for robustness and guaranteed minimum comprehensiveness.)