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

Sphinx (doc)

Sphinx est le nouvel outil python pour produire de la documentation python (à l’origine) ou autres (musique, commandes GNU/Linux, etc…). Il connait un très grand succès.

Source

gb_bigger

Other documentation links
  • http://jacobian.org/writing/great-documentation/what-to-write/ (Tech docs can take a bunch of different forms ranging from high-level overviews, to step-by-step walkthroughs, to auto-generated API documentation. Unfortunately, no single format works for all users; there’s huge differences in the way that people learn, so a well-documented project needs to provide many different forms of documentation)
# Add any Sphinx extension module names here, as strings. They can
# be extensions coming with Sphinx (named 'sphinx.ext.*') or your
# custom ones.
extensions = ['matplotlib.sphinxext.mathmpl',
          'matplotlib.sphinxext.only_directives',
          'matplotlib.sphinxext.plot_directive',
          'sphinx.ext.autodoc',
          'sphinx.ext.doctest',
          'ipython_console_highlighting',
          'inheritance_diagram',
          'numpydoc']
def fox_speed(size, weight, age):
	""" Return the maximum speed for a fox.

	:parameters:
		size
			The size of the fox (in meters)
		weight : float
			The weight of the fox (in stones)
		age : int
			The age of the fox (in years)

     """
     pass

# I think this last example is very readable in its ASCII form there, and
# will produce nicely formatted results in Sphinx (or epydoc for that matter).

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)

  • 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://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’)
  • http://doc.scrapy.org/index.html (‘Scrapy a is an application framework for crawling web sites and extracting structured data which can be used for a wide range of useful applications, like data mining, information processing or historical archivalManuel is all about making testable documents and well-documented tests. Of course, Python’s doctest module is a long-standing fixture in that space, so it only makes sense for Manuel to support doctest syntax‘)
  • http://www.ottohttp.org/docs/1.0/index.html (‘Otto is an HTTP publisher which uses a routes-like syntax to map URLs to code. It supports object traversal. You can use the publisher to write web applications. It was designed with both small and large applications in mind. In particular, it tries to conform to the Zen Of Python. )
  • http://packages.python.org/manuel/index.html (Manuel lets you mix and match traditional doctests with custom test syntax…‘)
  • http://codespeak.net/execnet/trunk/ (‘With execnet you can instantiate « gateways » between Python processes, use « remote_exec » code execution and « channels » to perform structured data communication.  See here for more info‘)
  • http://files.leosoto.com/dojdocs/html/index.html (‘Welcome to Django-Jython’s documentation!‘)
  • http://pyxb.sourceforge.net/index.html (‘PyXB (“pixbee”) is a pure Python package that generates Python source code for classes that correspond to data structures defined by XMLSchema. The generated classes support bi-directional conversion between XML documents and Python objects. In concept it is similar to JAXB for Java and CodeSynthesis XSD for C++. A Thirty Second Example is at the bottom of this page. Step-by-step examples are in User Reference.‘)
  • http://sweetapp.com/futures/ (‘The futures module provides a high-level interface for asynchronously executing functions and methods.’)
  • http://packages.python.org/errorhandler/ (This is a handler for the python standard logging framework that can be used to tell whether messages have been logged at or above a certain level.)
  • http://pybrain.org/docs/index.html (‘PyBrain’s concept is to encapsulate different data processing algorithms in what we call a Module. A minimal Module contains a forward implementation depending on a collection of free parameters that can be adjusted, usually through some machine learning algorithm.’)
  • http://pitz.tplus1.com/index.html (‘I really like Ditz. There’s a few tiny changes I want to make, so I’m making a python project, called pitz…Pitz uses yaml to serialize and unserialize data…Pitz uses IPython for the pitz-shell component and jinja2 to produce some output.’)
  • http://python-doit.sourceforge.net/index.html (‘doit comes from the idea of bringing the power of build-tools to execute any kind of task. It will keep track of dependencies between “tasks” and execute them only when necessary. It was designed to be easy to use and “get out of your way”.’)
  • http://matuson.com/code/schemaobject/ (‘SchemaObject provides a simple, easy to use Python object interface to a MySQL database schema. You can effortlessly write tools to test, validate, sync, migrate, or manage your schema as well as generate the SQL necessary to make changes to it.’)
  • http://coobs.eu.org/xrecord/api/tutorial.html (‘XRecord is an Object-Relational Mapper – a library which provides an object interface to databases. Tables are represented as classes, columns are attributes, and rows of data are class instances’)
  • http://viff.dk/doc/index.html (‘VIFF allows you to write a program which will interact with other programs in order to execute a joint computation. This is called a multi-party computation, MPC for short. VIFF allows you to do secure multi-party computations, in which a number of parties (three or more at the moment) execute a cryptographic protocol to do some joint computation. The computation could be anything, but elections and auctions are good examples of what you would want to do with secure multi-party computations (SMPC or simply MPC if it is implied that the protocol is secure). VIFF is implemented in Python using Twisted and should run on any platform where Python runs (succesfully tested on Linux, Windows, and Mac OS X). Please see the installation guide for details on the requirements.’)
  • http://csc.media.mit.edu/docs/index.html (‘Django is a Python framework for working with databases and web applications. All of ConceptNet is represented as Django models that interact with each other and with a database. We don’t use the web application part – not here, at least – but we provide the appropriate hooks so that ConceptNet can power a Django web application. (Because it does. It’s at http://openmind.media.mit.edu.)’)
  • http://www.briansimulator.org/docs/ (‘Brian is a clock driven simulator for spiking neural networks, written in the Python programming language. The simulator is written almost entirely in Python. The idea is that it can be used at various levels of abstraction without the steep learning curve of software like Neuron, where you have to learn their own programming language to extend their models‘)
  • http://packages.python.org/gitdb/ ( »The GitDB project implements interfaces to allow read and write access to git repositories. In its core lies the db package, which contains all database types necessary to read a complete git repository. These are the LooseObjectDB, the PackedDB and the ReferenceDB which are combined into the GitDB to combine every aspect of the git database.For this to work, GitDB implements pack reading, as well as loose object reading and writing. Data is always encapsulated in streams, which allows huge files to be handled as well as small ones, usually only chunks of the stream are kept in memory for processing, never the whole stream at once.’)
  • http://codespeak.net/tox/ (‘tox aims to automate state-of-the-art packaging, testing and deployment of Python software right from your console or CI server, invoking your tools of choice.’)
  • http://www.hardcoded.net/docs/hsaudiotag/ (‘hsaudiotag is a pure Python library that lets you read metadata (bitrate, sample rate, duration and tags) from mp3, mp4, wma, ogg, flac and aiff files. It can only read tags, not write to them, but unlike more complete libraries (like Mutagen), it is BSD licensed, making it suitable for most projects. It is also backed by a nifty test suite.’)
  • 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

Autres liens

Source: http://groups.google.com/group/sphinx-dev/browse_thread/thread/db7eafa20c1465d1

def fox_speed(size, weight, age):
	""" Return the maximum speed for a fox.

	:parameters:
		size
			The size of the fox (in meters)
		weight : float
			The weight of the fox (in stones)
		age : int
			The age of the fox (in years)

    """
    pass

# I think this last example is very readable in its ASCII form there, and
# will produce nicely formatted results in Sphinx (or epydoc for that matter).

//——————————————————————————- // @CR_Error_ConsumeBytes_FromCase // // Fonction : Consume Byte from a case. //            This function is called in case of errors. // Input    : The number of bytes to consume. // Retourne : Error code //——————————————————————————- void CR_Error_ConsumeBytes_FromCase(BYTE byNbBytesToConsum) { WORD wIndiceByte; BYTE byByte; for (   wIndiceByte = 0 ; (wIndiceByte < byNbBytesToConsum) ; wIndiceByte++) { if(!CR_WaitForCharReady(&byByte, TIMEOUT_HEADER_BASE_FRAME)) return; }return; }//——————————————————————————- // @CR_FrameCaseSize_Check // // Fonction : Check the length of a case frame. // Input    : byFrameCaseSize. //            pFunctionName // Retourne : Error code //——————————————————————————- DWORD CR_FrameCaseSize_Check(BYTE byFrameCaseSize, char *pCallingFunctionName) { if (byFrameCaseSize < 3) { char acBuffError[1000];if(gstCR.stLogFile.bEnableLog) { sprintf(acBuffError, « In %s byFrameCaseSize bad value:<%d>\n » , pCallingFunctionName , byFrameCaseSize);AddToLogBuff(acBuffError); }CR_Error_ConsumeBytes_FromCase(byFrameCaseSize); return CR_E_FAILED; } return CR_S_SUCCESS; } // CR_FrameCaseSize_Check()

Une Réponse to “Sphinx (doc)”

  1. […] Sphinx (doc) […]

Laisser un commentaire

Entrez vos coordonnées ci-dessous ou cliquez sur une icône pour vous connecter:

Logo WordPress.com

Vous commentez à l'aide de votre compte WordPress.com. Déconnexion / Changer )

Image Twitter

Vous commentez à l'aide de votre compte Twitter. Déconnexion / Changer )

Photo Facebook

Vous commentez à l'aide de votre compte Facebook. Déconnexion / Changer )

Photo Google+

Vous commentez à l'aide de votre compte Google+. Déconnexion / Changer )

Connexion à %s

 
%d blogueurs aiment cette page :