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

  • 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 à “Sphinx (doc)”

  1. Comment débuter pour documenter un projet python, C, admin, etc… avec le logiciel python sphinx de Georg Brandl « Le blog de Patrick Vergain a dit

    octobre 25, 2009 à 12:18

    [...] Sphinx (doc) [...]

    Réponse

Poster un commentaire

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

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

Annuler

Connexion à %s

 
Suivre

Recevez les nouvelles publications par mail.

Joignez-vous à 59 followers

%d bloggers like this: