Sphinx
Python Documentation Generator
Features
- Output Formats: HTML, LaTeX, Texinfo, man, plain text
- Cross References
- Hierarchical Structure
- Automatic Indices
- Syntax Highlighting (Pygments)
- Extensions
Projects Using Sphinx
- Python: http://docs.python.org/
- Django: http://docs.djangoproject.com/
- SciPy: http://docs.scipy.org/doc/scipy/reference/
- jsFiddle: http://doc.jsfiddle.net/
- Flask: http://flask.pocoo.org/docs/
- LLVM: http://llvm.org/
- Topaz: https://topaz.readthedocs.org/en/latest/
- Passy!! http://wak.rdrei.net/
Extensions
-
autodoc – Include documentation from docstrings
-
autosummary – Generate autodoc summaries
-
mathjax – Render math via JavaScript
-
coverage – Collect doc coverage stats
- ruby-domain – adds Ruby support
Read The Docs
Create, host, and browse documentation.
Community-driven documentation hub.
Getting Started
Install
pip install sphinx
Scaffolding
sphinx-quickstart
Building
make html
Documenting
TOC
.. toctree:: :maxdepth: 2 intro tutorial ...
Functions
.. py:function:: enumerate(sequence[, start=0]) Return an iterator that yields tuples of an index and an item of the *sequence*. (And so on.)
References
The :py:func:`enumerate` function can be used for ...
Autodoc
.. automodule:: io :members:
Domains
What are Domains?
- Early beginnings: Python
- Later: C
- >= 1.0.0: pluggable domains
Default Domain
.. default-domain:: name
JavaScript
.. js:function:: $.getJSON(href, callback[, errback]) :param string href: An URI to the location of the resource. :param callback: Get's called with the object. :param errback: Get's called in case the request fails. And a lot of other text so we need multiple lines :throws SomeError: For whatever reason in that case. :returns: Something
Moar Code
Blame da effin' WIFI!
.. code-block:: ruby Some Ruby code.
Line Numbers
.. code-block:: ruby :linenos: Some more Ruby code.
thx.
Sphinx
By Pascal
Sphinx
- 1,489
