What is Sphinx?¶
From http://sphinx-doc.org:
- Sphinx is a tool that makes it easy to create intelligent and beautiful documentation.
- It was originally created for the new Python documentation, and it has excellent facilities for the documentation of Python projects, but C/C++ is already supported as well.
Warning
... a great tool that actually makes programmers want to write documentation!
Sphinx Philosophy¶
Sphinx is a documentation generator. This means it takes plain-text files in reStructuredText format and transformes it into HTML, PDF, and any other output format.
reST -> Sphinx -> HTML (PDF, eBook, ...)
So as a user of Sphinx, your main job will be writing these text files with reStructuredText which is similar to Wiki languages like Markdown.
Sphinx Advantages¶
- Documents are written as plain text files.
- Output formats will be generated by Sphinx: HTML, PDF, eBook.
- Markup language used (reST) is similar to Wiki languages (Markdown, Textile, ...).
- Layouts can be replaced, many default layouts available.
- Writer concentrates on content, layout and output comes from Sphinx.
- Autogenerating documentation from source code.
- Syntax highlighting for many formats (Python, XML, ...).
- Cross-references to parts of the documenation (sections, code, glossary, ...) and automatic indices.
- Version control (GitHub) can be used for collaborative work and keeping track of different document versions.
- The documentation is part of the source code repository.
Examples on Sphinx¶
- https://docs.python.org/2.7/
- http://bokeh.pydata.org/en/latest/
- https://docs.djangoproject.com/en/1.9/internals/contributing/writing-documentation/
- http://docs.geotools.org/
- http://docs.geoserver.org/latest/en/user/
- http://ryan-roemer.github.io/sphinx-bootstrap-theme/
- http://cppformat.github.io/latest/
- http://doc.mapbender3.org/index.html