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

Archive for the ‘Documentation’ Category

La documentation associée aux logiciels

Sphinx developpment : Implemented improved glossary markup which allows multiple terms per definition.

Posted by patrick sur janvier 7, 2011

Implemented improved glossary markup which allows multiple terms per definition

+   In contrast to regular definition lists, *multiple* terms per entry are
+   allowed, and inline markup is allowed in terms.  You can link to all of the
+   terms.  For example::
+      .. glossary::
+         term 1
+         term 2
+            Definition of both terms.
+   (When the glossary is sorted, the first term determines the sort order.)
.. versionadded:: 0.6
You can now give the glossary directive a « :sorted:«  flag that will
automatically sort the entries alphabetically.

+   .. versionchanged:: 1.1
+      Now supports multiple terms and inline markup in terms.


--- a/tests/root/markup.txt
+++ b/tests/root/markup.txt
 .. glossary::
+   :sorted:
       Particle with integer spin.
-   fermion
+   *fermion*
       Particle with half-integer spin.
+   tauon
+   myon
+   electron
+      Examples for fermions.
+   über
+      Gewisse
+   änhlich
+      Dinge


This development is very interesting. Use of the visitor pattern.

. rst:directive:: .. glossary::
   This directive must contain a reST definition list with terms and
   definitions.  The definitions will then be referencable with the :rst:role:`term`
   role.  Example::
   This directive must contain a reST definition-list-like markup with terms and
   definitions.  The definitions will then be referencable with the
   :rst:role:`term` role.  Example::
      .. glossary::
@@ -169,10 +169,25 @@ Glossary
            The directory which, including its subdirectories, contains all
            source files for one Sphinx project.
   In contrast to regular definition lists, *multiple* terms per entry are
   allowed, and inline markup is allowed in terms.  You can link to all of the
   terms.  For example::
      .. glossary::
         term 1
         term 2
            Definition of both terms.
   (When the glossary is sorted, the first term determines the sort order.)
   .. versionadded:: 0.6
      You can now give the glossary directive a ``:sorted:`` flag that will
      automatically sort the entries alphabetically.
   .. versionchanged:: 1.1
      Now supports multiple terms and inline markup in terms.

Posted in 2011, Documentation, Doc_sphinx, python, reStructuredText, Sphinx | Leave a Comment »

Doxylink is a Sphinx extension to link to external Doxygen API documentation

Posted by patrick sur septembre 19, 2010


Doxylink is a Sphinx extension to link to external Doxygen API documentation.

It works much like the extlinks extension but it does some more processing to link C++ symbols against their Doxygen HTML documentation.

When generating your Doxygen documentation, you need to instruct it to create a ‘tag’ file. This is an XML file which contains the mapping between symbols and HTML files

Doxylink is a Sphinx extension to link to external Doxygen API documentation.

Posted in 2010, Années, C++, Documentation, Doc_sphinx, Génie logiciel, Langages, reStructuredText, Sphinx | Tagué: , , , | Leave a Comment »

PythonC 2.6 for Java : Py4J 0.4 is out

Posted by patrick sur septembre 19, 2010

Py4j (http://py4j.sourceforge.net/index.html)

Py4J enables Python programs running in a Python interpreter to dynamically access Java objects in a Java Virtual Machine. Methods are called as if the Java objects resided in the Python interpreter and Java collections can be accessed through standard Python collection methods. Py4J also enables Java programs to call back Python objects. Py4J is distributed under the BSD license.


See also

http://www.jython.org/index.html (« Python for the Java Platform »)

Py4J enables Python programs running in a Python interpreter to dynamically access Java objects in a Java Virtual Machine. Methods are called as if the Java objects resided in the Python interpreter and Java collections can be accessed through standard Python collection methods. Py4J also enables Java programs to call back Python objects. Py4J is distributed under the BSD license.

Posted in 2010, Années, Documentation, java, jython, Langages, python, Sphinx | Tagué: , , | Leave a Comment »

Python documentation: news sphinx/numpydoc + flexirest + sphinx sourceforge theme/{gsdview,bestgui}

Posted by patrick sur novembre 16, 2009

http://pypi.python.org/pypi/numpydoc/0.3.1 (Sphinx extension to support docstrings in Numpy format)

http://pypi.python.org/pypi/flexirest/ (‘ The medium-featured, flexible reStructuredText utility. Flexirest is a project that was born out of the authors long-running interest for reStructuredText, and the idea of writing everyday documents like letters, invoices and other simple documents in this way. Flexirest tries to strike a middle ground between docutils own command line tool chain (rst2html et al), that I find a little to minimalistic and Sphinx, that I find very nice but a little heavy to use for a quickie document like a random letter or some such. In short, the goal of flexirest is to enable you to use the reST format for everyday documents instead of a word processor or similar with minimal fuzz. Hence you get to stay in the comfy environment of your text editor and tool chain. And you can check in your docs in text format into your version control system of choice. And, if used correctly, you get to reuse a couple of stylings that you only need to create once. There are some modestly advanced tricks you can do too, primarily writing your own docutils roles, but I wouldn’t consider those the major points of flexirest. For more information on how to operate flexirest, see the quick manual.’)

http://groups.google.fr/group/sphinx-dev/browse_thread/thread/8e97570a6321dd8d?hl=fr (‘sphinx theme that could be useful to authors of sourceforge hosted projects. The look is more or less the same of the default theme but there are some facilities that could be useful.
A more detailed description of the theme can be found at:

And, finally, two projects of using it:

  • http://gsdview.sourceforge.net/ (‘GSDView (Geo-Spatial Data Viewer) is a lightweight viewer for geo-spatial data and products. It is written in python and Qt4 and it is mainly intended to be a graphical front-end for the GDAL library and tools. GSDView is modular and has a simple plug-in architecture.’)
  • http://bestgui.sourceforge.net/ (‘BESTGUI is a Graphical User Interface (GUI) for BEST written in Python and GTK+. The Basic Envisat SAR Toolbox (BEST) is a collection of executable software tools that has been designed to facilitate the use of ESA (the European Space Agency) SAR data. It operates according to user-generated parameters files. For more detail you should refer to the BEST Home Page.’)

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

Python : documentation technique de projets logiciels : un article de Jacob Kaplan-Moss (partie 1) / Django / sphinx

Posted by patrick sur novembre 12, 2009

Source: http://jacobian.org/writing/great-documentation/what-to-write/

Voici quelques extraits intéressants:

I love Django’s documentation. It clocks in at about 700 pages printed, and most of it is clear, concise, and helpful. I think Django’s among the best documented open source projects, and nothing makes me prouder.

Today I’ll discuss the different forms technical documentation can take, and where to focus your efforts.



Good tutorials are a must as they’re usually the first thing someone sees when trying out a new piece of tech. First impressions are incredibly important: that rush of success as you work through a good tutorial will likely color your future opinions about the project….Be quick. At some conference or another I heard someone — I think it was Kathy Sierra — say that, as a rule of thumb, a new user should be able to experience success within thirty minutes…

Topical guides

This is the meat of your documentation. Once somebody’s learned (from a tutorial) the high-level concepts, they’re going to need to dive into the details of some area or another. Any documentation worth its salt is going to have a whole bunch of these — Django’s got about 35 different topical guides, covering each conceptual area (e.g. models, sessions, testing, etc.)…The main goal for topical coverage should be comprehensiveness. The reader ought to come away from a close read feeling very comfortable with the topic in question. They should feel that they know the vast majority of the possible options, and more importantly they should understand how all the concepts fit together.

Unfortunately there aren’t a lot of projects that do these very well. Most have reasonable tutorials, many have okay-to-good reference material, but most seem to leave the topical guides to books.



Finally, you need complete reference for all the public APIs your project provides. These should be designed for those who already know how to use some API, but need to look up the exact arguments some function takes, or how a particular setting influences behavior, etc…It’s important to point out that reference material is not in any way a substitute for good tutorials and guides!..Think of guides and reference as partners: guides give you the “why,” and reference gives you the “how.”

It’s really tempting to use an auto-documentation tool like Javadoc or RDoc for reference material.


Auto-generated documentation is almost worthless. At best it’s a slightly improved version of simply browsing through the source, but most of the time it’s easier just to read the source than to navigate the bullshit that these autodoc tools produce. About the only thing auto-generated documentation is good for is filling printed pages when contracts dictate delivery of a certain number of pages of documentation. I feel a particularly deep form of rage every time I click on a “documentation” link and see auto-generated documentation.

There’s no substitute for documentation written, organized, and edited by hand.

I’ll even go further and say that auto-generated documentation is worse than useless: it lets maintainers fool themselves into thinking they have documentation, thus putting off actually writing good reference by hand. If you don’t have documentation just admit to it. Maybe a volunteer will offer to write some! But don’t lie and give me that auto-documentation crap.

A voir

–  http://www.djangoproject.com/ (‘Django is a high-level Python Web framework that encourages rapid development and clean, pragmatic design.’)

http://www.django-fr.org/ (‘Django est un framework écrit en Python. Puissant, il est utilisé par des organisations comme la Nasa, le Washington Times et a servi de base à Google App Engine. Mais Django est aussi adapté si vous n’êtes pas une multinationale ou une agence gouvernementale‘)


Posted in Django, Documentation, python, Python Web Frameworks, Sphinx | Tagué: | Leave a Comment »

Des nouvelles de python : Guido Van Rossum et la documentation avec sphinx/rest , numpy, scipy, ipython

Posted by patrick sur novembre 9, 2009

Documentation rest/sphinx


Guido Van Rossum

http://neopythonic.blogspot.com/2009/11/python-in-scientific-world.html (‘...After the meeting, Fernando showed me a little about how NumPy is maintained. They have elaborate docstrings that are marked up with a (very light) variant of Sphynx, and they let the user community edit the docstrings through a structured wiki-like setup. Such changes are then presented to the developers for review, and can be incorporated into the code base with minimal effort.

An important aspect of this approach is that the users who edit the docstrings are often scientists who understand the computation being carried out in its scientific context, and who share their knowledge about the code and its background and limitations with other scientists who might be using the same code. This process, together with the facilities in IPython for quickly calling up the docstring for any object, really improves the value of the docstrings for the community. Maybe we could use something like this for the Python standard library; it might be a way that would allow non-programmers to help contribute to the Python project (one of the ideas also mentioned in the diversity discussions).’)
http://fdoperez.blogspot.com/2009/11/guido-van-rossum-at-uc-berkeleys.html (‘…I wanted both to thank him for creating and shepherding such a high-quality language for us scientists, and to establish a good line of communication with him (and indirectly the core python development group) so that he can understand better what are some of the use patterns, concerns and questions we may have regarding the language.I have the impression that in this we were successful, especially as we had time after the open presentations for a more detailed discussion of how we use and develop our tools. Most of us in scientific computing end up spending an enormous amount of time with open interpreter sessions, typically IPython ones (I started the project in the first place because I wanted a very good interactive environment, beyond Python’s default one), and in this work mode the key source of understanding for code are good docstrings. This is an area where I’ve always been unhappy about the standard library, whose docstrings are typically not very good (and often they are non-existent). We showed Guido the fabulous Numpy/Scipy docstring editor by Pauli Virtanen and Emmanuelle Gouillart, as well as the fact that Numpy has an actual docstring standard that is easy to read yet fairly complete. I hope that this may lead in the future to an increase in the quality of the Python docstrings, and perhaps even to the adoption of a more detailed docstring standard as part of PEP 8, which I think would be very beneficial to the community at large…’)A voir:



Extensions sphinx


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

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 »

Les nouveaux projets python: codereview/rietveld, Paver, Sphinx

Posted by patrick sur mai 12, 2008


http://googleappengine.blogspot.com/2008/05/open-source-app-rietveld-code-review.html (« My first project as a Google engineer was an internal web app for code review. According to Wikipedia, code review is « systematic examination (often as peer review) of computer source code intended to find and fix mistakes overlooked in the initial development phase, improving both the overall quality of software and the developers’ skills. » Not an exciting topic, perhaps, but the internal web app, which I code-named Mondrian after one of my favorite Dutch painters, was an overnight success among Google engineers (who evidently value software quality and skills development :-). I even gave a public presentation about it: you can watch the video on YouTube.« )

http://groups.google.com/group/codereview-discuss?hl=en (« Discussion of the code review tool « Rietveld », http://codereview.appspot.com, open source at http://code.google.com/p/rietveld/.« )


http://www.blueskyonmars.com/projects/paver/ (« Paver is a Python-based build/distribution/deployment scripting tool along the lines of Make or Rake. What makes Paver unique is its integration with commonly used Python libraries. Common tasks that were easy before remain easy. More importantly, dealing with yourKevin Dangoor of SitePen applications specific needs and requirements is now much easier…Paver is currently alpha release software. There is one major feature (zc.buildout integration) planned for 1.0. At this point, it is unlikely that there will be significant changes to the pavement syntax, but there are no guarantees. If there are breaking changes, they will almost certainly be minor…Paver was created by . »)

http://groups.google.com/group/comp.lang.python.announce/browse_thread/thread/1b84e15dab7f02d6?hl=en (« With Version 0.7, Paver is now a full stand-in for the traditional distutils- or setuptools-based setup.py. Need to perform some extra work before an sdist runs? No problem:

def sdist():
…move files around, etc….
call_task(« distutils.command.sdist »)

You put that in your pavement.py file and now running « paver sdist » will perform your logic and then run the distutils sdist command. Paver can even generate a setup.py so « python setup.py sdist » or « python setup.py install » work just as they always have. And to make it easier for people who don’t yet have Paver, you can include a small zip file that enables « python setup.py install » to work off of a pavement.py file even without Paver. Paver 0.7 has a bunch of new tools to help with project documentation (taking advantage of Georg Brandl’s Sphinx and also including Ned Batchelder’s Cog). Paver now includes much better docs, too.« )

http://nedbatchelder.com/code/cog/ (« Cog is a code generation tool. It lets you use pieces of Python code as generators in your source files to generate whatever code you need…Cog transforms files in a very simple way: it finds chunks of Python code embedded in them, executes the Python code, and inserts its output back into the original file. The file can contain whatever text you like around the Python code. It will usually be source code« )


http://sphinx.pocoo.org/ (« Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects, written by Georg Brandl and licensed under the BSD license.It was originally created to translate the new Python documentation, but has now been cleaned up in the hope that it will be useful to many other projects. (Of course, this site is also created from reStructuredText sources using Sphinx!) »)

A voir:

http://en.wikipedia.org/wiki/Code_review (« Code reviews can often find and remove common vulnerabilities such as format string exploits, race conditions, memory leaks and buffer overflows, thereby improving software security. Online software repositories based on Subversion with Trac, Mercurial, GIT or others allow groups of individuals to collaboratively review code. Additionally, specific tools for collaborative code review can facilitate the code review process. »)

http://en.wikipedia.org/wiki/Software_distribution (« A software distribution is a bundle of a specific software (or a collection of multiple, even an entire operating system), already compiled and configured. It is generally the closest thing to a turnkey form of a usually GPL or open source source code for a software. It usually takes the form of either rpm, deb, tgz, msi, exe etc. installer and is downloadable from the Internet. These are also known as a Binary distributions…The Python programming language offers a distribution utility called distutils, which requires the creation of a setup.py configuration file »)

http://docs.python.org/dist/dist.html (« Distributing Python Modules »)

http://mail.python.org/mailman/listinfo/doc-sig (« For discussion of both the form and content of Python documentation. The SIG should work towards setting up a Python Documentation Project effort like the Linux Documentation Project. « )

http://fr.wikipedia.org/wiki/Documentation_logicielle (« La documentation logicielle est un texte écrit qui accompagne le logiciel informatique. Elle explique comment le logiciel fonctionne, ou comment on doit l’employer. Le terme peut avoir des significations différentes pour des personnes de différents profils.La documentation constitue une partie importante de l’ingénierie logicielle, qui est trop souvent négligéeDonald Knuth a insisté sur le fait que la documentation peut être un processus très difficile de réflexion après coup et a recommandé la programmation lettrée, qui consiste à écrire la documentation en même temps et en un même lieu que le code source et à l’extraire par des moyens automatiques. »)

http://fr.wikipedia.org/wiki/Gestion_de_configuration (« La gestion de configuration consiste à gérer la description technique d’un système (et de ses divers composants), ainsi qu’à gérer l’ensemble des modifications apportées au cours de l’évolution du système. La gestion de configuration est utilisée pour la gestion de systèmes complexes« )

http://en.wikipedia.org/wiki/Software_deployment (« Software deployment is all of the activities that make a software system available for use. The general deployment process consists of several interrelated activities with possible transitions between them. These activities can occur at the producer site or at the consumer site or both. Because every software system is unique, the precise processes or procedures within each activity can hardly be defined. Therefore, « deployment » should be interpreted as a general process that has to be customized according to specific requirements or characteristics. A brief description of each activity will be presented later. »)

Posted in Distribution de logiciel, Documentation, Génie logiciel, Gestion de projet, Gestion de version, python, Revue de code | Tagué: | Leave a Comment »