"…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…"

Posts Tagged ‘reStructuredText’

Documentation de python 2.6 grâce à sphinx

Posted by patrick sur 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.


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.
Documentation and code for the Sphinx toolchain.
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!‘)


Posted in Documentation, python, Sphinx | Tagué: , , | Leave a Comment »

Comment débuter pour documenter un projet python, C, admin, etc… avec le logiciel python sphinx de Georg Brandl

Posted by patrick sur octobre 25, 2009



Voici quelques liens pour bien débuter une documentation d’un projet avec sphinx. J’ai commencé à écrire une page https://pvergain.wordpress.com/sphinx-doc/ pour rassembler la documentation qui pour moi était la plus intéressante. J’ai inséré ci-dessous la liste des principaux liens.

Je mets à jour une liste des projets utilisant sphinx. Les 3 derniers en date (22 octobre 2009) sont https://wiki.fysik.dtu.dk/ase/https://wiki.fysik.dtu.dk/gpaw/index.html et http://openalea.gforge.inria.fr/doc/openalea/doc/build/html/index.html.

Merci à Georg Brandl alias Birkenfeld (http://twitter.com/birkenfeld, http://pythonic.pocoo.org/ , http://pythonic.pocoo.org/tags/sphinx ) et aussi Uli Fouquet, Andre Roberge, Armin Ronacher,  Tim Golden and Mark Summerfield  pour ce magnifique logiciel.


Projets utilisant sphinx

Builtin sphinx extensions

These extensions are built in and can be activated by respective entries in the extensions configuration value:

Third-party extensions

There are several extensions that are not (yet) maintained in the Sphinx distribution. The Wiki at BitBucket maintains a list of those.

If you write an extension that you think others will find useful, please write to the project mailing list (sphinx-dev@googlegroups.com) and we’ll find the proper way of including or hosting it for the public.

Utiliser sphinx avec:

Autres  projets utilisant sphinx (non listés sur sphinx.pocoo.org)

  • Projets sphinx concernant des projets non “python”

A lire

Autres liens

A voir

http://en.wikipedia.org/wiki/ReStructuredText (‘reStructuredText is a lightweight markup language intended to be highly readable in source format. Its formal name indicates that it is a « revised, reworked, and reinterpreted StructuredText. »[1] reStructuredText is sometimes abbreviated as RST; while sometimes abbreviated as ReST or reST, this can create confusion with REST, an unrelated technology.’)

Posted in 2009, Années, Documentation, Génie logiciel, python, Sphinx | Tagué: , , , , , , , , , | Leave a Comment »