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

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

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‘)

 

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

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

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:

• Distribute documentation: http://packages.python.org/distribute
• Bootstrap file to install Distribute: http://python-distribute.org/distribute_setup.py
• Bootstrap file for zc.buildout: http://python-distribute.org/bootstrap.py

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

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

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

 

fOSSa Conference – Free and Open Source Software Academic Conference, november 17-18, 2009 Grenoble

Source: http://www.ow2.org/view/Events/fOSSaConferenceGrenobleFrance

fOSSa

 

Date: November 17-18, 2009
Venue: World Trade Center, Grenoble, France
Practical information, detailed program and registration: http://fossa.inrialpes.fr/2009/

Conference overview
The “fOSSa” conference (Free/Open Source Software Academics) is co-organised by INRIA and OW2 Europe Local Chapter. It will review Open Source fundamentals and will present innovating Open Source project as well as communities experiences. fOSSa is the first international Open Source Conference event located in Grenoble! The fOSSa audience mainly focuses on academia and research centres but does not close the door to industrials as in many cases academia needs industrials and vice versa: we believe that Open Source model can improve such kind of collaboration in a much more natural way.

DAY 1 is focusing on the Open Source model basics:

1. OSS and Benefits for Academic projects
2. OSS and Innovation for Academic projects
3. OSS and Business Models for Academic projects
4. OSS and the Law for Academic projects
5. OSS and Communities for Academic projects
6. OSS and European Commission fo Academic projects
7. OSS and Market Needs for Academic projects

DAY 2, practical session including with real life examples of the OSS fundamentals, will address:

1. OSS and Collaboration for Academic projects
2. OSS and Promotion for Academic projects
3. OSS and Governance for Academic projects
4. OSS and Quality for Academic projects
5. OSS and the Law for Academic projects

Day 2, 10-10-10 presentation

In parallel, OW2 academic projects will be presented in a 10-10-10 formula style1. PLUMES/FEATHER community will present scientific Open Source academic projects, and sessions will be booked for Open Source Start-up’s presentation.

(1) 10 minutes presentation -10 minutes demo -10 minutes questions/answers.

Participants
Apache, Eclipse, Engineering, HP Fossology, INRIA, Mandriva, OW2, Sun Microsystem, University Paris VII, University of Milano…

 

 

 

 

fOSSa conférence sur le libre/open-source d’envergure Internationale les 17-18 novembre 2009 à Grenoble

Source

INRIA Rhone-Alpes / D2T / OW2 Europe Local Chapter
fOSSa Steering Committee / QualiPSo / NESSI OSS WG

fOSSa (Free Open Source Software for Academia) est organisée conjointement par le chapitre local Europe d’OW2 et l’INRIA.

L’histoire du logiciel libre débute dans les années 70 grâce aux universitaires et chercheurs académiques: pour cette communauté, distribuer un code informatique sous une licence permissive était une règle naturelle. Depuis, le monde du logiciel libre connaît un succès extraordinaire à travers, en outre, le monde industriel. Cependant, les objectifs initiaux défini par le monde académique semble, aujourd’hui, être oubliés.

Le programme couvre les aspects fondamentaux du logiciel libre/open-source (modèles économiques, licences, collaboration, communautés, promotion, exploitation) et propose des retours d’expérience ainsi que des présentations de projets innovants.  Elle s’adresse au monde académique/universitaire, mais aussi aux industriels dans la mesure où les relations recherche/industrie sont de plus en plus souvent au coeur de développements collaboratifs libres/open-source: fOSSa propose de repositionner le Libre au centre des collaborations recherche-industrie.

Les intervenants sont, en autre, Clément Escoffier (Apache), Ralph Mueller (Directeur Fondation Eclipse Europe), HP Fossology (Bob Gobeille et Bruno Cornec), INRIA (Luc Grateau et Jean Bernard Stefani), Arnaud Laprévote (Directeur R&D Mandriva), Cédric Thomas (OW2 Consortium CEO), Roberto Di Cosmo (CIRILL & Mancoozi), Plumes (Jean Luc Archimbaud et Teresa Gomez DIaz) …

Date : 17-18 Novembre 2009
Lieu : World Trade Center – Grenoble – France
Programme & Inscription (gratuite): http://www.ow2.org/fossaconference

Documentation de python 2.6 grâce à sphinx

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!‘)

 

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

sphinx

Voici quelques liens pour bien débuter une documentation d’un projet avec sphinx. J’ai commencé à écrire une page http://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.

• http://sphinx.pocoo.org/ (’Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.It was originally created to translate the new Python documentation, and it has excellent support for the documentation of Python projects, but other documents can be written with it too. Of course, this site is also created from reStructuredText sources using Sphinx!’)
• http://matplotlib.sourceforge.net/sampledoc/ (’This is a tutorial introduction to quickly get you up and running with your own sphinx documentation system. We’ll cover installing sphinx, customizing the look and feel, using custom extensions for embedding plots, inheritance diagrams, syntax highlighted ipython sessions and more. If you follow along the tutorial, you’ll start with nothing and end up with this site – it’s the bootstrapping documentation tutorial that writes itself!‘)
• http://matplotlib.sourceforge.net/sampledoc/getting_started.html (’Installing your doc directory’)
• http://matplotlib.sourceforge.net/sampledoc/cheatsheet.html#this-file
• Very nice sphinx doc:
  • https://wiki.fysik.dtu.dk/ase/ (’The Atomic Simulation Environment (ASE) is the common part of the simulation tools developed at CAMd. ASE provides Python modules for manipulating atoms, analyzing simulations, visualization etc.’)
    • https://wiki.fysik.dtu.dk/ase/development/writing_documentation_ase.html
  • http://matplotlib.sourceforge.net/
  • http://www.buildout.org/index.html (’Buildout is a Python-based build system for creating, assembling and deploying applications from multiple parts, some of which may be non-Python-based. It lets you create a buildout configuration and reproduce the same software later. ‘)
  • https://wiki.fysik.dtu.dk/gpaw/index.html (’GPAW is a density-functional theory (DFT) Python code based on the projector-augmented wave (PAW) method. It uses real-space uniform grids and multigrid methods or atom-centered basis-functions. Read more about its features and the algorithms used.’)
    • https://wiki.fysik.dtu.dk/gpaw/devel/writing_documentation.html
  • http://sagemath.org/doc/developer/index.html (’Sage is a free mathematics software system. It is implemented using Python, Cython, and C++, uses GAP, GSL, Matplotlib, Maxima, MWRANK, NetworkX, NTL, Numpy, PARI, Singular and many specialized systems and libraries. It is free and open source, and is available under the terms of the GNU Public License. Some parts are available under compatible licenses.’)
  • http://openalea.gforge.inria.fr/doc/openalea/doc/build/html/index.html (’OpenAlea is an open source project primarily aimed at the plant research community, with a particular focus on Plant Architecture Modeling at different scales. It is a distributed collaborative effort to develop Python libraries and tools which address the needs of current and future work in Plant Architecture modeling’)
    • http://openalea.gforge.inria.fr/doc/openalea/misc/doc/html/misc/openalea_misc_sphinx_tools_ref.html#module-sphinx_tools
    • https://gforge.inria.fr/frs/?group_id=79

    • svn checkout svn://scm.gforge.inria.fr/svn/openalea/trunk openalea

Projets utilisant sphinx

• http://sphinx.pocoo.org/examples.html
  
  • APSW: http://apsw.googlecode.com/svn/publish/index.html
  • boostmpi: http://documen.tician.de/boostmpi/
  • Calibre: http://calibre.kovidgoyal.net/user_manual/
  • Chaco: http://code.enthought.com/projects/chaco/docs/html/
  • CodePy: http://documen.tician.de/codepy/
  • Cython: http://docs.cython.org/
  • C\C++ Python language binding project: http://language-binding.net/index.html
  • Director: http://packages.python.org/director/
  • Djagios: http://djagios.org/
  • Django: http://docs.djangoproject.com/
  • F2py: http://www.f2py.org/html/
  • GeoDjango: http://geodjango.org/docs/
  • GeoServer: http://docs.geoserver.org/
  • Glashammer: http://glashammer.org/
  • Grok: http://grok.zope.org/doc/current/
  • Hedge: http://documen.tician.de/hedge/
  • IFM: http://fluffybunny.memebot.com/ifm-docs/index.html
  • Jinja: http://jinja.pocoo.org/2/documentation/
  • LEPL: http://www.acooke.org/lepl/
  • MapServer: http://mapserver.org/
  • Matplotlib: http://matplotlib.sourceforge.net/
  • Mayavi: http://code.enthought.com/projects/mayavi/docs/development/html/mayavi
  • MeshPy: http://documen.tician.de/meshpy/
  • MirrorBrain: http://mirrorbrain.org/docs/
  • Mixin.com: http://dev.mixin.com/
  • mpmath: http://mpmath.googlecode.com/svn/trunk/doc/build/index.html
  • MyHDL: http://www.myhdl.org/doc/0.6/
  • NetworkX: http://networkx.lanl.gov/
  • NumPy: http://docs.scipy.org/doc/numpy/reference/
  • ObjectListView: http://objectlistview.sourceforge.net/python
  • OpenEXR: http://excamera.com/articles/26/doc/index.html
  • OpenLayers: http://docs.openlayers.org/
  • openWNS: http://docs.openwns.org/
  • Paste: http://pythonpaste.org/script/
  • Paver: http://www.blueskyonmars.com/projects/paver/
  • Py on Windows: http://timgolden.me.uk/python-on-windows/
  • PyCuda: http://documen.tician.de/pycuda/
  • PyEphem: http://rhodesmill.org/pyephem/
  • Pyevolve: http://pyevolve.sourceforge.net/
  • PyLit: http://pylit.berlios.de/ ( Literate Programming with reStructuredText)
  • Pylo: http://documen.tician.de/pylo/
  • Pylons: http://docs.pylonshq.com/
  • PyMOTW: http://www.doughellmann.com/PyMOTW/
  • PyPubSub: http://pubsub.sourceforge.net/
  • pyrticle: http://documen.tician.de/pyrticle/
  • Pysparse: http://pysparse.sourceforge.net/
  • Python: http://docs.python.org/
  • python-apt: http://people.debian.org/~jak/python-apt-doc/
  • PyUblas: http://documen.tician.de/pyublas/
  • Quex: http://quex.sourceforge.net/
  • Reteisi: http://docs.argolinux.org/reteisi/
  • Roundup: http://www.roundup-tracker.org/
  • Sage: http://sagemath.org/doc/
  • Satchmo: http://www.satchmoproject.com/docs/svn/
  • Scapy: http://www.secdev.org/projects/scapy/doc/
  • Selenium: http://seleniumhq.org/docs/
  • Self: http://selflanguage.org/
  • SimPy: http://simpy.sourceforge.net/ (SimPy (= Simulation in Python) is an object-oriented, process-based discrete-event simulation language based on standard Python . It provides the modeler with components of a simulation model including processes, for active components like customers, messages, and vehicles, and resources, for passive components that form limited capacity congestion points like servers, checkout counters, and tunnels…)
  • Sphinx: http://sphinx.pocoo.org/
  • Sprox: http://sprox.org/
  • SQLAlchemy: http://www.sqlalchemy.org/docs/
  • Sqlkit: http://sqlkit.argolinux.org/
  • SymPy: http://docs.sympy.org/
  • tinyTiM: http://tinytim.sourceforge.net/docs/2.0/
  • The Wine Cellar Book: http://www.thewinecellarbook.com/doc/en/
  • TurboGears: http://turbogears.org/2.0/docs/
  • VOR: http://www.vor-cycling.be/
  • WebFaction: http://docs.webfaction.com/
  • WFront: http://discorporate.us/projects/WFront/
  • WTForms: http://wtforms.simplecodes.com/docs/
  • Zope 3: e.g. http://docs.carduner.net/z3c-tutorial/
  • zc.async: http://packages.python.org/zc.async/1.5.0/

Builtin sphinx extensions

• http://sphinx.pocoo.org/extensions.html#builtin-sphinx-extensions
• http://matplotlib.sourceforge.net/sampledoc/extensions.html

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

• sphinx.ext.autodoc – Include documentation from docstrings
  • Docstring preprocessing
  • Skipping members
• sphinx.ext.autosummary – Generate autodoc summaries
  • sphinx-autogen – generate autodoc stub pages
  • Generating stub pages automatically
  • Customizing templates
• sphinx.ext.doctest – Test snippets in the documentation
  • This extension allows you to test snippets in the documentation in a natural way. It works by collecting specially-marked up code blocks and running them as doctest tests.
  • http://jessenoller.com/2009/02/26/sphinx-and-auto-buildingtests/ (’…Ok, so I’m think I’m in sphinx-love. I’ve needed to really begin a largish documentation project for a code base I own and drive (omgmanagerspeak) and since I’d rather not completely rely on API docs, and I have exposure to sphinx courtesy of python-core work, I chose you sphinx-a-chu! Sphinx really is awesome. I started just chugging through the docs, and ended up pulling from tip (via mercurial) and using the latest version for the theme support Georg added recently. Rather than rehash the basics, I’ll simple explain my setup, and why I love it – starting with the output from sphinx-quickstart which kicks out a makefile for you, I immediately turned on the ‘sphinx.ext.autodoc‘ and ‘sphinx.ext.doctest‘ extensions – the former allows you to tell sphinx (in your rst file) to delegate the documentation for this class/method/etc to the API docs, and the latter allows you to pass the examples/snippets you will have through doctest. These two things make writing/testing the docs awesome – but it gets more awesome...’)
  • http://aroberge.blogspot.com/2008/03/inspiration-and-persistence.html (’… inspired by an earlier post on Georg Brand’s remarkable Sphinx, Crunchy now includes a prototype for an automated documentation testing framework along the lines of sphinx.ext.doctest which was released yesterday. My intention is to update Crunchy’s implementation so that it can be totally compatible with Sphinx’s. And while I believe that this is a neat (and fun!) thing to include in Crunchy, it only very indirectly contribute to my overall goal and ends up delaying the 1.0 release for Crunchy...’)
  • http://svn.turbogears.org/docs/2.0/docs/conf.py
• sphinx.ext.intersphinx – Link to other projects’ documentation
• Math support in Sphinx
  • sphinx.ext.pngmath – Render math as PNG images
  • sphinx.ext.jsmath – Render math via JavaScript
• sphinx.ext.graphviz – Add Graphviz graphs
• sphinx.ext.inheritance_diagram – Include inheritance diagrams
• sphinx.ext.refcounting – Keep track of reference counting behavior
• sphinx.ext.ifconfig – Include content based on configuration
• sphinx.ext.coverage – Collect doc coverage stats
• sphinx.ext.todo – Support for todo items

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.

• ascii (aafigure for sphinx, http://packages.python.org/sphinxcontrib-aafig/ )

• http://projects.scipy.org/numpy/browser/trunk/doc/sphinxext/numpydoc.py
  • http://nipy.sourceforge.net/nipy/documentation.html (très belle documentation produite avec l’extension ci-dessus)
  • http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
  • http://svn.scipy.org/svn/numpy/trunk/doc/example.py
  • http://nipy.sourceforge.net/devel/
    • http://nipy.sourceforge.net/devel/guidelines/howto_document.html (’Nipy uses the Sphinx documentation generating tool. Sphinx translates reST formatted documents into html and pdf documents. All our documents and docstrings are in reST format, this allows us to have both human-readable docstrings when viewed in ipython, and web and print quality documentation.’)
    • http://nipy.sourceforge.net/devel/guidelines/sphinx_helpers.html
  • UML
    • http://www.shibu.jp/sdeditext/
    • http://bitbucket.org/shibu/sdeditext_for_sphinx/

    

Utiliser sphinx avec:

• doxygen
  • http://github.com/michaeljones/breathe (’Restructured text and Sphinx bridge to Doxygen‘)

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

• http://docs.scipy.org/doc/ (’Welcome! This is the documentation for Numpy and Scipy .’)
• http://nipy.sourceforge.net/devel/ (’The purpose of NIPY is to make it easier to do better brain imaging research.’)
• http://ipython.scipy.org/doc/manual/html/index.html
• http://doc.freevo.org/api/kaa/base/core/index.html
• http://11craft.github.com/duruses/
• http://www.buildout.org/index.html
• http://11craft.github.com/duruses/index.html
  • http://11craft.github.com/duruses/api.html#module-duruses.client
  • http://11craft.github.com/duruses/sources/api.txt
• http://www.voidspace.org.uk/python/mock/
• http://infinitemonkeycorps.net/docs/pph/ (’You have a pile of Python code. You think, “this could be useful to someone else.” You want to release it as an open-source project. You’ve come to the right place.’)
• http://doc.bazaar-vcs.org/en/ (’Documentation for Bazaar 2.0- The Adaptive Version Control System’)
• http://packages.python.org/pypng/
• http://www.pyside.org/docs/pyside/index.html (’PySide aims to provide Python developers access to the Qt libraries in the most natural way’)
• https://wiki.fysik.dtu.dk/ase/ (’The Atomic Simulation Environment (ASE) is the common part of the simulation tools developed at CAMd. ASE provides Python modules for manipulating atoms, analyzing simulations, visualization etc.’)
  • https://wiki.fysik.dtu.dk/ase/development/writing_documentation_ase.html

• Projets sphinx concernant des projets non “python”

• • http://www.nongnu.org/gsl-shell/index.html
  • http://nicolas.steinmetz.fr/tutoriels/index.html
  • http://catherinedevlin.pythoneers.com/

A lire

• http://pythonic.pocoo.org/ (’Le blog de Georg Brandl’)
• http://www.pythonprogramminglanguage.info/2009/10/02/bookrest-the-stylesheet-editor-in-action/
• http://pylonsbook.com/en/1.0/documentation.html#introducing-sphinx

• http://pyfound.blogspot.com/2008/08/georg-brandl-and-brett-cannon-to.html (”At the July 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.’)
• http://pythonic.pocoo.org/2009/9/12/new-in-sphinx-1-0-domains (’)
• http://bitbucket.org/birkenfeld/sphinx-domains (’…Anyway, when domain support is fully implemented, and assuming someone writes a JavaScript domain extension, you will be able to document a JavaScript project (or a mixed project) with Sphinx just as comfortably as you document a Python project right now…’)
• http://www.voidspace.org.uk/python/weblog/arch_d7_2008_11_22.shtml (’…This is timely as one of the most valuable things that I learned at PyWorks (in the hallway track) was how to use Sphinx. Chris Perkins (who has some patches that will be integrated into the next release) showed me how to get started. My conclusion – Sphinx is frickin awesome!..’)
• http://tarekziade.wordpress.com/2008/03/23/sphinx-as-a-doc-builder-for-python-projects/ (’…Sphinx annoucement is really exciting, and it shouldn’t be too much pain to bundle it in a buildout recipe to manage a project documentation. Since it is based on templates and configuration files, a default structure can be generated to startup a project documentation together with a code base...’)

Autres liens

• http://code.google.com/p/docpicture/ (’Alternative to Python help() enabling viewing of embedded pictures‘)
• http://www.packtpub.com/article/documenting-your-python-project-1 (’…Documentation is work that is often neglected by developers and sometimes by managers. This is often due to a lack of time towards the end of development cycles, and the fact that people think they are bad at writing. Some of them are bad, but the majority of them are able to produce fine documentation...’)

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

Python choisi pour l’enseignement de l’algorithmique en classe de seconde pour la rentrée 2009/2010 en France

C’est en lisant le magazine hors série N°37 ‘Tangente (http://www.tangente-education.com, “Les algorithmes au coeur du raisonnement structuré“)  que j’ai appris que le langage python faisait partie des 2 principaux langages de programmation recommandés pour l’apprentissage de l’algorithmique en classe de seconde ! C’est une bonne nouvelle pour les élèves et pour python également . C’est aussi dans ce même magazine que j’ai appris que l’algorithmique était désormais inscrite dans les programmes de lycées !

Le magazine va proposer un manuel interactif en cours de préparation (http://www.tangente-education.com/ManuelTangente2/mansec/manuelseconde/home/index/)

Autre source pour cette nouvelle:

• • http://scratch.mit.edu/forums/viewtopic.php?id=22097 (‘ET OUI l’an prochain il y aura un peu d’algorithmique à enseigner en classe de Seconde : Voilà le lien :Eduscol Mathématiques…Scratch (le deuxième langage recommandé)…est cité en exemple dans ces documents.‘)
    La page d’accès aux ressources
    Le lien pour le document ressource pour l’enseignement de l’algorithmique
    Ressources pour la Classe de Seconde – Algorithmique
    Le lien pour le document ressource pour l’enseignement des probabilités et statistiques
    Ressources pour la Classe de Seconde – Probabilités Statistiques
    Le lien pour le document ressource pour l’enseignement de la logique
    Ressources pour la Classe de Seconde – Notations et raisonnement mathématiques
    Le lien pour le document ressource pour l’enseignement des fonctions
    Ressources pour la Classe de Seconde – Fonctions

Voici quelques liens sur les mathématiques avec python:

• http://mail.python.org/mailman/listinfo/edu-sig (‘This list is for discussion of Python in education, however (at the request of a majority of readers) explicitly excluding educational politics’)
• http://wiki.python.org/moin/PythonInEducation
  • http://wiki.python.org/moin/SchoolsUsingPython (‘This is a listing of schools that are using Python in their curriculum.’)
• http://www.pyromaths.org/ (‘Pyromaths est un programme qui permet de générer des fiches d’exercices de mathématiques de collège ainsi que leur corrigé. Il crée des fichiers au format pdf qui peuvent ensuite être imprimés ou lus sur écran.’)
  • Les sources de Pyromaths
• http://www.inforef.be/swi/python.htm
• http://www.scipy.org/ (‘SciPy (pronounced “Sigh Pie”) is open-source software for mathematics, science, and engineering. It is also the name of a very popular conference on scientific programming with Python. The SciPy library depends on NumPy, which provides convenient and fast N-dimensional array manipulation. The SciPy library is built to work with NumPy arrays, and provides many user-friendly and efficient numerical routines such as routines for numerical integration and optimization. Together, they run on all popular operating systems, are quick to install, and are free of charge. NumPy and SciPy are easy to use, but powerful enough to be depended upon by some of the world’s leading scientists and engineers. If you need to manipulate numbers on a computer and display or publish the results, give SciPy a try!‘)
• http://neuroimaging.scipy.org/site/index.html (‘The neuroimaging in python (NIPY) project is an environment for the analysis of structural and functional neuroimaging data. It currently has a full system for general linear modeling of functional magnetic resonance imaging (fMRI).’)
• http://code.google.com/p/spyderlib/ (Spyder (previously known as Pydee) is a Python development environment providing MATLAB-like features in a simple and light-weighted software, available for Microsoft Windows XP/Vista, GNU/Linux and MacOS X.)
• http://www.pythonxy.com/foreword_fr.php (‘Python(x,y) est un logiciel libre scientifique de calcul numérique basé sur le langage Python, les interfaces graphiques Qt (et le cadre de développement associé), l’environnement de développement Eclipse et l’environnement de développement scientifique interactif Spyder.’)
• http://www.sagemath.org/
  • http://www.sagemath.org/fr/tutorial/index.html (‘Sage est un logiciel mathématique libre destiné à la recherche et à l’enseignement en algèbre, géométrie, arithmétique, théorie des nombres, cryptographie, calcul scientifique et dans d’autres domaines apparentés. Le modèle de développement de Sage comme ses caractéristiques techniques se distinguent par un souci extrême d’ouverture, de partage, de coopération et de collaboration : notre but est de construire la voiture, non de réinventer la roue. L’objectif général de Sage est de créer une alternative libre viable à Maple, Mathematica, Magma et MATLAB….le public visé par Sage comprend les étudiants (du lycée au doctorat), les enseignants et les chercheurs en mathématiques. Le but est de fournir un logiciel qui permette d’explorer toutes sortes de constructions mathématiques et de faire des expériences avec, en algèbre, en géométrie, en arithmétique et théorie des nombres, en analyse, en calcul numérique, etc. Sage facilite l’expérimentation interactive avec des objets mathématiques’)

Autres liens sur l’apprentissage de python

• http://www.python.org/doc/essays/cp4e.html (‘We intend to start with Python, a language designed for rapid development. We believe that Python makes a great first language to learn: Unlike languages designed specifically for beginners, Python is also the choice of many programming professionals. It has an active, growing user community which has already expressed much interest in this proposal, and we expect that this will be a fertile first deployment ground for the teaching materials and tools we propose to create. During the course of the research we will evaluate Python and propose improvements or alternatives…Python is a good language for teaching absolute beginners… by Guido Van Rossum, http://www.python.org/~guido/ ‘)
• http://wiki.python.org/moin/BeginnersGuide (‘New to programming? Python is free, and easy to learn if you know where to start! This guide will help you to get started quickly.‘)
• http://www.afpy.org/ (‘L’Association Francophone Python est une association pour la promotion du langage Python’)
• http://wikipython.flibuste.net/ (‘Bienvenue sur ce Wiki-Python : site autogéré sur le langage Python‘)
• http://rgruet.free.fr/ (‘Just try Python! I suggest that you download the official distribution, or the ActivePython distribution, and then start here.‘)
• http://docs.python.org/ (Python 2.6)
• http://docs.python.org/tutorial/ (‘Python is an easy to learn, powerful programming language. It has efficient high-level data structures and a simple but effective approach to object-oriented programming. Python’s elegant syntax and dynamic typing, together with its interpreted nature, make it an ideal language for scripting and rapid application development in many areas on most platforms.’)
• http://docs.python.org/dev/ (Python 2.7)
• http://docs.python.org/3.1/ (Python 3.1)
• http://docs.python.org/dev/py3k/ (Python 3.2)
• http://diveintopython3.org/ (‘Dive Into Python 3 covers Python 3 and its differences from Python 2. Compared to Dive Into Python, it’s about 20% revised and 80% new material. The book is now complete, but feedback is always welcome.’)
• http://wiki.python.org/moin/Languages/French?highlight=%28CategoryLanguage%29
• http://pypi.python.org/pypi (‘The Python Package Index is a repository of software for the Python programming language’)
• http://ocw.mit.edu/OcwWeb/Electrical-Engineering-and-Computer-Science/6-00Fall-2008/CourseHome/index.htm(‘Introduction to Computer Science and Programming. This subject is aimed at students with little or no programming experience. It aims to provide students with an understanding of the role computation can play in solving problems. It also aims to help students, regardless of their major, to feel justifiably confident of their ability to write small programs that allow them to accomplish useful goals. The class will use the Python™ programming language.’)

• http://www.openbookproject.net/pybiblio/ (‘ Welcome to the Python Bibliotheca! This site aims to be both a library of educational materials using Python to teach computer programming, and a virtual meeting place for teachers and students engaged in learning and teaching using Python.’)

• http://www.openbookproject.net/pybiblio/gasp/course/ (‘There are a lot of worksheets in our beginners’ Python course. The most important are the five numbered sheets; you should work your way through those. But they’ll be pretty hard going unless you also make use of the lettered sheets, which give you useful information about particular topics.’)
• http://www.openbookproject.net/pybiblio/gasp/course/1-intro.html (‘Introducing Python, first steps’)
• http://www.openbookproject.net/thinkcs/python/english2e/ (‘How to Think Like a Computer Scientist. Learning with Python 2nd Edition by Jeffrey Elkner, Allen B. Downey, and Chris Meyers. This book is marked up in ReStructuredText using a document generation system called Sphinx.The source code is located on the Launchpad website at http://bazaar.launchpad.net/~thinkcspy/thinkcspy/english2e/files.’)

Les projets python de la semaine 37: Tornado (web) , sqlkit (database), HeeChee (mercurial-subversion), sinthgunt (video, ffmpeg)

• http://www.tornadoweb.org/ (‘Tornado is an open source version of the scalable, non-blocking web server and tools that power FriendFeed. The FriendFeed application is written using a web framework that looks a bit like web.py or Google’s webapp, but with additional tools and optimizations to take advantage of the underlying non-blocking infrastructure. The framework is distinct from most mainstream web server frameworks (and certainly most Python frameworks) because it is non-blocking and reasonably fast. Because it is non-blocking and uses epoll, it can handle thousands of simultaneous standing connections, which means it is ideal for real-time web services. We built the web server specifically to handle FriendFeed’s real-time features — every active user of FriendFeed maintains an open connection to the FriendFeed servers. (For more information on scaling servers to support thousands of clients, see The C10K problem…Tornado has been tested on Python 2.5 and 2.6. To use all of the features of Tornado, you need to have PycURLsimplejson installed and a JSON library like )’)
  • http://github.com/dustin/tornado/tree/master ( a port of the tornado web framework to twisted.)
  • http://glyph.twistedmatrix.com/2009/09/what-i-wish-tornado-were.html (‘In the course of developing Tornado, there are several things that FriendFeed could have done to move the Twisted community forward, at no cost to themselves.  I don’t want to rag on FriendFeed, or Bret Taylor, or Facebook here; they’re not the first to re-write something without communicating.  In fact I recently had almost this exact same discussion with another project that did the same thing.  Since Tornado is such a high-profile example, though, I want to draw attention to the problem so that there’s some hope that maybe the next project won’t forget to communicate first.’)
  • http://glyph.twistedmatrix.com/2009/09/tornado-twisted.html (‘Many kudos to Dustin Sallings, who has already created a branch of Tornado which uses Twisted for both networking and HTTP parsing, in probably less time than it took me to write my previous post about how somebody should do that.  Awesome!
    (The method it uses is currently a little weird, where you create a “Site” object, but it looks like it would be pretty simple to use a Resource instead if you were so inclined.)’)

• http://www.aeracode.org/2009/9/10/announcing-heechee/ (…One of the particular issues I have is with svn:externals. A lot of apps – including some we have at work – rely on svn:externals to pull in external dependencies into a libs folder along with the project itself. Externals is one of the few features of subversion that I thought was pretty much perfect, and it was sad to see my move to Mercurial break it… One of the questions led him onto hg-git – the awesome git backend plugin for Mercurial, that the GitHub guys wrote – and how they first investigated the idea of an svn gateway to expose their repositories transparently to subversion users. From what I gathered, subversion’s wire format proved too tricky to deal with, and so they turned elsewhere…After some digging, reading an obscure academic paper and liberal application of Wireshark, I grew confident enough that I could at least implement something. A day later, and I’d like to present the very first version of what I’m calling Heechee (if you get the pun, ten nerd points). Heechee is a transparent mercurial-as-subversion gateway. It serves a Mercurial repository as a Subversion WebDAV-based repository. It’s still in the early stages, but at the moment it will serve its own mercurial repository to subversion in such a way that you can check out the repository, and update to various revisions within it.You can check it out at BitBucket. It’s pretty alpha code, and make sure you have the dependencies mentioned in the README, but it works, which greatly surprises me. I plan to much improve the code to support more ‘advanced’ features, like being able to do more than checkout and update, as well as exposing tags and branches correctly. There’s even the chance I’ll stick Git support in, when I’ve had a play with Dulwich.)

• http://sqlkit.argolinux.org/ (‘Sqlkit is a mini framework based on pygtk that provides some very powerfull classes to edit databases. It’s meant as a base for database desktop applications. Sqlkit is based on:

• Python
• Pygtk
• sqlalchemy (>=0.5)
• python_dateutils
• babel for localization
• the correct driver for your database of choice‘).

Un autre projet similaire est camelot basé sur pyQt (http://pypi.python.org/pypi/Camelot/).

• http://code.google.com/p/sinthgunt/ (‘Sinthgunt is an open source graphical user interface for ffmpeg, a computer program that can convert digital audio and video into numerous formats. Using pre-configured conversion settings, it makes the task of converting between different media formates very easy.‘)