Documentation de python 2.6 grâce à sphinx
Publié par patrick le octobre 27, 2009
L’utilisation de sphinx pour la documentation python faisait partie des nouveautés de la version 2.6.1 sortie le 1er octobre 2008.
- http://docs.python.org/whatsnew/2.6.html
New Documentation Format: reStructuredText Using Sphinx¶
The Python documentation was written using LaTeX since the project started around 1989. In the 1980s and early 1990s, most documentation was printed out for later study, not viewed online. LaTeX was widely used because it provided attractive printed output while remaining straightforward to write once the basic rules of the markup were learned.
Today LaTeX is still used for writing publications destined for printing, but the landscape for programming tools has shifted. We no longer print out reams of documentation; instead, we browse through it online and HTML has become the most important format to support. Unfortunately, converting LaTeX to HTML is fairly complicated and Fred L. Drake Jr., the long-time Python documentation editor, spent a lot of time maintaining the conversion process. Occasionally people would suggest converting the documentation into SGML and later XML, but performing a good conversion is a major task and no one ever committed the time required to finish the job.
During the 2.6 development cycle, Georg Brandl put a lot of effort into building a new toolchain for processing the documentation. The resulting package is called Sphinx, and is available from http://sphinx.pocoo.org/.
Sphinx concentrates on HTML output, producing attractively styled and modern HTML; printed output is still supported through conversion to LaTeX. The input format is reStructuredText, a markup syntax supporting custom extensions and directives that is commonly used in the Python community.
Sphinx is a standalone package that can be used for writing, and almost two dozen other projects (listed on the Sphinx web site) have adopted Sphinx as their documentation tool.
See also:
- Documenting Python (http://docs.python.org/documenting/index.html#documenting-index)
- Describes how to write for Python’s documentation.
- Sphinx
- Documentation and code for the Sphinx toolchain.
- Docutils
- The underlying reStructuredText parser and toolset.
