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

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:
 
    boson
       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.

• https://bitbucket.org/birkenfeld/sphinx/changeset/32c4f57a02c9
  • CHANGES (3 lines added, 0 lines removed)
  • doc/markup/para.rst (18 lines added, 3 lines removed)
  • sphinx/addnodes.py (3 lines added, 0 lines removed)
  • sphinx/domains/std.py (86 lines added, 22 lines removed)
  • sphinx/roles.py (0 lines added, 1 lines removed)
  • sphinx/writers/html.py (4 lines added, 0 lines removed)
  • sphinx/writers/latex.py (5 lines added, 1 lines removed)
  • sphinx/writers/manpage.py (4 lines added, 0 lines removed)
  • sphinx/writers/texinfo.py (3 lines added, 0 lines removed)
  • sphinx/writers/text.py (4 lines added, 0 lines removed)
  • tests/root/markup.txt (13 lines added, 1 lines removed)

. rst:directive:: .. glossary::
155	155
156		This directive must contain a reST definition list with terms and
157		definitions. The definitions will then be referencable with the :rst:role:`term`
158		role. Example::
	156	This directive must contain a reST definition-list-like markup with terms and
	157	definitions. The definitions will then be referencable with the
	158	:rst:role:`term` role. Example::
159	159
160	160	.. glossary::
161	161
…	…	@@ -169,10 +169,25 @@ Glossary
169	169	The directory which, including its subdirectories, contains all
170	170	source files for one Sphinx project.
171	171
	172	In contrast to regular definition lists, *multiple* terms per entry are
	173	allowed, and inline markup is allowed in terms. You can link to all of the
	174	terms. For example::
	175
	176	.. glossary::
	177
	178	term 1
	179	term 2
	180	Definition of both terms.
	181
	182	(When the glossary is sorted, the first term determines the sort order.)
	183
172	184	.. versionadded:: 0.6
173	185	You can now give the glossary directive a ``:sorted:`` flag that will
174	186	automatically sort the entries alphabetically.
175	187
	188	.. versionchanged:: 1.1
	189	Now supports multiple terms and inline markup in terms.

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

http://packages.python.org/sphinxcontrib-doxylink/

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.

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

- 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://bitbucket.org/esmljaos/flexirest/overview/ (The medium-featured, flexible reStructuredText utility)

- 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:

• http://sourceforge.net/apps/trac/gsdview/browser/trunk/doc/themes/sourceforge
  
• http://sourceforge.net/apps/trac/gsdview/browser/trunk/doc/themes/sourceforge/README.txt‘)

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.’)

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

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:

- http://docs.scipy.org/numpy/Front%20Page/

 

Extensions sphinx

• http://pypi.python.org/pypi/sphinxcontrib-sdedit/0.3 (‘Sphinx extension for drawing sequence diagrams This package contains the Sphinx extension for sdedit.’)