Comment débuter pour documenter un projet python, C, admin, etc… avec le logiciel python sphinx de Georg Brandl
Publié par patrick le octobre 25, 2009
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.’)
- 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.’)
- 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
- sphinx.ext.autosummary – Generate autodoc summaries
- 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.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
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://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.’)
- Projets sphinx concernant des projets non “python”
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.’)
