"…mais ce serait peut-être l'une des plus grandes opportunités manquées de notre époque si le logiciel libre ne libérait rien d'autre que du code…"

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.
Voir aussi :)
- http://pyfound.blogspot.com/2008/08/georg-brandl-and-brett-cannon-to.html (‘At the July (2008) Board meeting of the PSF Board of Directors, PSF Community Awards were awarded to Georg Brandl and Brett Cannon.Georg has been an enthusiastic contributor to the core for several years, and a while ago stunned the Python development world by building the Sphinx documentation system as an alternative to the LaTeX-based system we had been using previously, and converting the Python documentation to use it. Brett has also been an active core developer for many years, but was nominated for his infrastructure work in migrating the Python bug-tracking system off of SourceForge to our own Roundup instance, and for his efforts keeping the Python developer introduction updated. Georg and Brett richly deserve recognition for their contributions. Congratulations to Brett and Georg, and thanks for all your hard work!‘)

 

About these ads

Laisser un commentaire

Entrez vos coordonnées ci-dessous ou cliquez sur une icône pour vous connecter:

Logo WordPress.com

Vous commentez à l'aide de votre compte WordPress.com. Déconnexion / Changer )

Image Twitter

Vous commentez à l'aide de votre compte Twitter. Déconnexion / Changer )

Photo Facebook

Vous commentez à l'aide de votre compte Facebook. Déconnexion / Changer )

Photo Google+

Vous commentez à l'aide de votre compte Google+. Déconnexion / Changer )

Connexion à %s

 
Suivre

Recevez les nouvelles publications par mail.

Joignez-vous à 74 followers

%d bloggers like this: