Author: tziade Date: Sat Apr 1 22:46:49 2006 New Revision: 2756 Modified: cookbook/trunk/recipe50.en.tex Log: finished translation
Modified: cookbook/trunk/recipe50.en.tex ============================================================================== --- cookbook/trunk/recipe50.en.tex (original) +++ cookbook/trunk/recipe50.en.tex Sat Apr 1 22:46:49 2006 @@ -49,30 +49,27 @@ Using this document, she creates the code following these steps: \begin{itemize} -\item Transcripting in a reST document (doctest) the specifications; +\item Translating in a reST document (doctest) the specifications; \item inserting code examples, that fullfills the features asked; \item coding the underlying code, so the examples in the document works for real. \end{itemize} -\subsection*{Transcripting the need into a doctest file} -xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +\subsection*{Translating the need into a doctest file} -Transcrire en doctest les besoins exprim�s se fait en synth�tisant au maximum le -cahier des charges, et en d�crivant la structure du paquet qui va �tre -d�velopp�. - -Prenons l'exemple d'un module en charge de r�cup�rer des flux RSS pour les -stocker dans des objets Python persistants, puis les rendre affichables dans -l'application. Le d�veloppeur d�cide d'organiser son paquet en trois modules: +Translating in doctests the needs is done by summarrizing the specifications, +and by describing the future package structure. + +Let's code for example a package that handles the retrieval of RSS feeds to +store them in persistent Python objects, then provide web views. The developer +decides to organize the package in three modules: \begin{itemize} -\item \code{rssfetcher.py}: module en charge de la r�cup�ration des flux RSS; -\item \code{rssobject.py}: module en charge de la cr�ation et du stockage -des donn�es; -\item \code{rssview.py}: module en charge de l'affichage des donn�es. +\item \code{rssfetcher.py}: module for RSS retrieval; +\item \code{rssobject.py}: module for creating and storing data; +\item \code{rssview.py}: module for viewing data. \end{itemize} -\noindent Il commence par �crire quatre fichiers doctests, qui expriment cette +\noindent She starts to write four doctests files, that shows the future code structure: \begin{itemize} \item \code{README.txt} @@ -81,55 +78,51 @@ \item \code{rssview.txt} \end{itemize} -Le fichier \code{README.txt} d�crit en quelques phrases l'objectif du paquet, -et pr�sente sa structure. +The \code{README.txt} file describe in a few sentences the package goal, and +present its structure. -\codetitle{Fichier README.txt} +\codetitle{README.txt file:} \begin{Verbatim} rssreader ========= -Ce paquet permet de pr�senter des flux rss. Il est organis� en trois -composants: +This package knows how to display RSS feeds. It is organized in three modules. -- rssfetcher: sait lire un flux RSS 1.0 -- rssobject: stocke le flux et fourni des m�thodes d'acc�s -- rssview: sait afficher un flux dans le navigateur +- rssfetcher: knows how to read RSS 1.0 feeds +- rssobject: store the feeds and provides accessors +- rssview: know how to display a feed in the browser \end{Verbatim} -\noindent Chaque module est pr�sent� � son tour dans un doctest. +\noindent Each module then has its own doctest file. -\codetitle{Fichier rssfetcher.txt} +\codetitle{rssfetcher.txt file:} \begin{verbatim} rssfetcher ========== -Le module rssreader transforme un fichier XML au format RSS 1.0 -vers une structure Python exploitable. Il est invoqu� avec l'URL -d'un flux et renvoi une liste contenant les entr�es du flux. +rssfetcher module transforms a RSS 1.0 XML file into a Python usable structure. +It is called with the feed URL and returns a list with the feed entries. \end{verbatim} -A ce stade, le d�veloppeur n'a pas encore �crit de code, mais -dispose d'une sp�cification technique et architecturelle exploitable. +At this point the developer didn't write any code, but has a first draft of +the package structure and technical specifications. This step reveals sometimes +some incoherences in the needs. -\subsection*{Ins�rer des exemples de codes} +\subsection*{Inserting code examples} -Sur la base de ces fichiers textes, le d�veloppeur peut commencer -� pr�parer le d�veloppement des modules, en explicitant la face -visible de ces derniers, c'est � dire les API qui seront utilis�es -dans d'autres modules. +Using these text files, the developer can start to define each module high level +public elements, that will be used by other modules. -\codetitle{Modification du fichier rssfetcher.txt} +\codetitle{Changing rssfetcher.txt:} \begin{verbatim} rssfetcher ========== -Le module rssfetcher transforme un fichier XML au format RSS 1.0 -vers une structure Python exploitable. Il est invoqu� avec l'URL -d'un flux et renvoi une liste contenant les entr�es du flux. +rssfetcher module transforms a RSS 1.0 XML file into a Python usable structure. +It is called with the feed URL and returns a list with the feed entries. -Il fourni une fonction `fetchFeed(source)` qui renvoie une structure Python -en fonction d'une URL ou d'un fichier :: +It provides a `fetchFeed(source)` function that returns a Python structure, +given an URL or a file :: >>> from rssfetcher import fetchFeed >>> fetchFeed('tests/rss.xml') @@ -137,39 +130,42 @@ \end{verbatim} \begin{codenotes} -\item Le paquet doit pr�voir dans un sous r�pertoire un fichier -�chantillon \code{rss.xml}, contenant un flux utilis� pour les tests. +\item At this point the package will need a \code{rss.xml} file to be used as a +sample for tests. \end{codenotes} -\noindent Ce principe est appliqu� pour l'ensemble des modules du paquet, -susceptibles de fournir des fonctionnalit�s. +\noindent This principle is used for all modules that might provide public +functionalities. -\subsection*{D�velopper les fonctionnalit�s} +\subsection*{Coding functionalities} -Le doctest pr�c�dent ne peut bien s�r fonctionner que si l'impl�mentation -est r�alis�e. Le d�veloppeur con�oit donc le module \code{rssfetcher.py} -jusqu'� ce que le test du doctest passe. Ce d�veloppement n�cessitera -certainement la cr�ation d'autres tests unitaires, qui seront -con�us classiquement dans des classes dans le sous-r�pertoire de \code{tests}. - -Lorsque tous les modules sont con�us, \code{README.txt} contient un exemple -complet d'utilisation, qui simule g�n�ralement quelques directives ZCML -et quelques �changes avec le publisher. - -\section*{Maintenir et faire �voluer le code} - -L'�volution du paquet, que ce soit dans le cadre d'une correction, ou -d'une modification, doit se faire de la m�me mani�re: les fichiers textes -sont revus en premiers, puis le code est modifi� en cons�quence. - -Les corrections de bogues sont trait�s d'une mani�re particuli�re: -un test unitaire qui reproduit le probl�me est ajout� dans les classes de -tests, et le code invoqu� corrig�. Ajouter ces tests dans les doctests -d�nature leur objectif secondaire: servir de documentation. - -Cependant, si il est explicitement demand� que les bugfix soient document�s, -et facilement lisibles, un doctest \code{bugfix.txt} peut �tre ajout�. -Ce n'est pas le cas pour Zope 3 par exemple, car le couple tracker+svn fourni -une bonne tracabilit� des bugfix. +The previous doctest cannot work until the functionalitie is really +implemented. The developer codes the \code{rssfetcher.py} module until +the tests passes. By doing so, new tests will certainly be done, but +in classical unit tests in a \code{tests} subfolder. This will avoid adding +tests in the doctests files and make them unreadable with implementation +level matters. + +When all modules are done, \code{README.txt} needs to contain a full example +on how to use the feature, and will probably have to simulate a few ZCML +directives and a few data exchanges with the publisher, through a functional +doctest. + +\section*{Maintaining and making the code evolve} + +The package evolution, for a correction or a modification, needs to be +done the same way: texte files are first reviewed, then the code is +consequently modified. + +Bug fixes are treated in a particular way: a unit test that reproduces +the problem is added in the unit tests modules, and the incriminated +code corrected. Those tests aren't to be added in doctests, to avoid +making them unreadable and lose their first intent: being part of the +documentation. + +On the other hand, if it's explicitely asked that bugfixes should be +documented and easily readable, a \code{bugfix.txt} can be added to collect +them. This is not the case for such project as Zope 3 because they provide +enough feedback on bugfixes with the tracker and the subversion system. \end{solution} \end{document} -- http://lists.nuxeo.com/mailman/listinfo/z3lab-checkins