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

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.

 

Tutorials

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.

 

Reference

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.

Don’t.

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 »

Python : Distribute 0.6.8 (http://python-distribute.org/) , pip 0.6 , virtualenv 1.4.1 : make the transition today :)

Posted by patrick sur novembre 10, 2009

Source: http://s3.pixane.com/pip_distribute.png

distribute, pip virtualenv
curl  -0 http://python-distribute.org/distribute_setup.py > distribute_setup.py
sudo python distribute_setup.py
sudo easy_install -U pip

http://pypi.python.org/pypi/pip/0.6 (‘pip is a replacement for easy_install. It uses mostly the same techniques for finding packages, so packages that were made easy_installable should be pip-installable as well…The main website for pip is pip.openplans.org. You can also install the in-development version of pip with easy_install pip==dev. ‘)

http://pypi.python.org/pypi/virtualenv/1.4.2 (‘virtualenv is a successor to workingenv, and an extension of virtual-python.’)

More informations


source: http://mail.python.org/pipermail/distutils-sig/2009-November/014229.html 

On behalf of the Distribute team, I am pleased to announce the 0.6.7
release of Distribute.

As usual, availabe at PyPI: http://pypi.python.org/pypi/distribute

Most noticeable changes in 0.6.7 are:

- now the develop command supports the --user option, so it can use
the per-user site packages (PEP 370)
- the generated scripts now wrap their call to the script entry point
in the standard "if name == 'main'"
- better errors handling in PackageIndex when files and pages are
visited by easy_install
- a virtualenv-compatible version, so the next virtualenv release will
be able to provide a --distribute option.

You can visit http://pypi.python.org/pypi/distribute#id2 for a full
CHANGES list.

We are now starting the 0.6.8 work in parallel of 0.7.x development,
with more bugfixes coming up.

http://python-distribute.org/

This is just a placeholder for bootstrap files for Distribute, and nightly builds for Distutils

Useful links:

http://faassen.n–tree.net/blog/view/weblog/2009/11/09/0 (‘A history of Python packaging’)

http://s3.pixane.com/python_comrades.png

guido van rossum

Posted in 2009, distribute, package_management, python | 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

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

 

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