Commits

Benoît Bryon  committed a2f47fc

Reviewed projects and french articles: using Sphinx.

  • Participants
  • Parent commits 6b589b7

Comments (0)

Files changed (14)

File en/index.txt

 
 .. lang:: fr
 
-   * `Canaliser les flux de communication <../fr/articles/canaliser-les-flux-de-communication>`_
-   * `Organiser les répertoires d'un projet <../fr/articles/organisation-repertoires-projet-deploiement>`_
-   * `Pourquoi documenter ? <../fr/articles/documentation>`_
-   * `Django et reverse() <../fr/articles/django-reverse-lazy>`_
+   * `Canaliser les flux de communication
+     <../fr/articles/canaliser-les-flux-de-communication.html>`_
+   * `Organiser les répertoires d'un projet
+     <../fr/articles/organisation-repertoires-projet-deploiement.html>`_
+   * `Pourquoi documenter ? <../fr/articles/documentation.html>`_
+   * `Django et reverse() <../fr/articles/django-reverse-lazy.html>`_
 
 Elsewhere...
 ============
 * :doc:`projects/django-downloadview`
 * :doc:`projects/diecutter`
 * :doc:`projects/xal`
-* and :doc:`more <projects/index>`...
 
 Find out more on my `Github <https://github.com/benoitbryon>`_ and
 `Bitbucket <https://bitbucket.org/benoitbryon/>`_ profiles.
 Talks
 *****
 
-* Diecutter: templates as a service,
-  proposed as a poster session for
+* "Diecutter: templates as a service",
+  a poster session for
   EuroPython 2013, Florence, Italy
 
-* XAL: execution abstraction layer,
-  proposed as a poster session for
+* "XAL: execution abstraction layer",
+  a poster session for
   EuroPython 2013, Florence, Italy
 
-* WriteTheDocs.org: Sphinx documentation toolkit,
-  proposed as a poster session for
+* "WriteTheDocs.org: Sphinx documentation toolkit",
+  a poster session for
   EuroPython 2013, Florence, Italy
 
-* Don't fear the buildout, at DjangoCon-Toulouse 2012
+* "Don't fear the buildout",
+  a lightning-talk
+  at DjangoCon-Toulouse 2012
 
 * .. lang:: fr
 
-     Valorisez votre documentation at DjangoCon-Toulouse 2012
+     "Valorisez votre documentation"
+     un lightning-talk
+     à DjangoCon-Toulouse 2012
 
 * and :doc:`more <talks/index>`...
 

File en/projects/diecutter-directory.png

Added
New image

File en/projects/diecutter-file.png

Added
New image

File en/projects/diecutter.txt

 diecutter - Templates as a service
 ##################################
 
-* https://github.com/novagile/diecutter
+`diecutter`_ is a file generation service. It has been created to generate code
+or configuration files.
+
+Basically, you POST data to templates (resources) and it returns generated
+files.
+
+.. image:: diecutter-file.png
+   :alt: Client posts DATA to TEMPLATE which returns FILE
+
+Directories are rendered as archives.
+
+.. image:: diecutter-directory.png
+   :alt: Client posts DATA to DIRECTORY which returns ARCHIVE
+
+`Rémy Hubscher`_ and I created and maintain diecutter.
+
+We are to talk about it during a poster session, at EuroPython 2013 in
+Florence, Italy.
+
+
+.. rubric:: References
+
+.. target-notes::
+
+.. _`diecutter`: https://diecutter.readthedocs.org
+.. _`Rémy Hubscher`: https://github.com/Natim

File en/projects/django-downloadview.txt

 django-downloadview
 ###################
 
-* https://github.com/benoitbryon/django-downloadview
+`django-downloadview`_ provides generic views to make Django serve files.
+
+It can serve files from models, storages, local filesystem, arbitrary URL...
+and even generated files.
+
+For increased performances, it can delegate the actual streaming to a reverse
+proxy, via mechanisms such as Nginx's X-Accel.
+
+I created django-downloadview from code found in some `Novapost`_'s Django
+applications. I almost rewritten it all since the first release.
+
+
+.. rubric:: References
+
+.. target-notes::
+
+.. _`django-downloadview`: https://pypi.python.org/pypi/django-downloadview
+.. _`Novapost`: http://www.novapost.fr

File en/projects/index.txt

 Projects
 ########
 
+Here is a selection of projects I work (or worked) on.
+
 .. toctree::
-   :maxdepth: 1
    :titlesonly:
 
    writethedocs

File en/projects/python-hospital.txt

 :lang: en
 
-##############################
-python-hospital, django-doctor
-##############################
+#################################
+python-hospital, django-doctor...
+#################################
 
-* http://github.com/python-hospital
+"Health checks", "diagnosis", "`smoke tests`_" or whatever the name, are
+kind of tests. They give you feedback about the status of some running product.
+They are part of supervision and monitoring.
+
+`python-hospital`_ is an "in-development" working group around health checks
+for `Python`_ software, such as a WSGI application.
+
+
+**********
+My 2 cents
+**********
+
+As a Django user, I needed health checks. I first found `django-doctor`_.
+I contributed to it, introducing the "`TestCase-like health checks`_" feature.
+
+Then I discovered two other projects: `django-health-check`_ and
+`django-smoketest`_.
+
+Since projects are very similar, I'm trying to get the authors work together.
+That's why I created `python-hospital`_ organization.
+I'm currently discussing with authors about vision and features... i.e. trying
+to form a team.
+
+I also initiated `hospital`_ project, which is a generic Python project that
+could be used by Django-specific ones, because some "health check" features
+aren't specific to Django and could be used by many Python projects.
+
+
+.. rubric:: References
+
+.. target-notes::
+
+.. _`smoke tests`: https://en.wikipedia.org/wiki/Smoke_testing
+.. _`python-hospital`: https://github.com/python-hospital
+.. _`Python`: https://python.org
+.. _`django-doctor`: https://pypi.python.org/pypi/django-doctor/
+.. _`TestCase-like health checks`:
+   https://github.com/funkbit/django-doctor/pull/2
+.. _`django-health-check`: https://pypi.python.org/pypi/django-health-check/
+.. _`django-smoketest`: https://pypi.python.org/pypi/django-smoketest/
+.. _`hospital`: https://github.com/python-hospital/hospital

File en/projects/writethedocs.txt

 :lang: en
 
 ##############
-Write the docs
+Write The Docs
 ##############
 
-* http://docs.writethedocs.org
-* http://github.com/benoitbryon/rst2rst
+`Write The Docs`_ is about documentation, from the writers' side:
+
+* a place where community of documentation writers can meet ;
+* a collection of user stories about writing documentation ;
+* a set of best practices ;
+* a consistent set of tools and recipes to actually make it.
+
+See `Write The Docs documentation`_.
+
+
+**********
+My 2 cents
+**********
+
+I have been working on the documentation topic since 2010. So, when Write The
+Docs project started in 2013, I was proud to contribute:
+
+* migrated my own `Docness`_ project to docs.writethedocs.org.
+
+* I'm developing and promoting some tools that help apply the recommendations:
+
+  * `sphinxcontrib.testbuild`_: make sure your Sphinx builds actually build.
+  * `rst2rst`_: a tool to apply some style-guide to reStructuredText documents.
+    The next step would be some "rstlint" application.
+  * if nobody does it, I guess I'll develop some "generic doctest" extension
+    for Sphinx, in order to test examples in any language (Shell, ruby...).
+    Maybe my other project :doc:`xal` would help.
+
+* I proposed a poster session to `EuroPython 2013 in Florence, Italy`_.
+  I'll try to promote Write The Docs project and to find contributors (Python
+  developers) for the tools we need!
+
+I'm a contributor and have been granted commit permission on the main
+repository!
+
+
+.. rubric:: References
+
+.. target-notes::
+
+.. _`Write The Docs`: http://writethedocs.org
+.. _`Write The Docs documentation`: http://docs.writethedocs.org
+.. _`docness`: https://github.com/benoitbryon/docness
+.. _`sphinxcontrib.testbuild`:
+   https://pypi.python.org/pypi/sphinxcontrib-testbuild
+.. _`rst2rst`: https://pypi.python.org/pypi/rst2rst
+.. _`EuroPython 2013 in Florence, Italy`:
+   https://ep2013.europython.eu

File en/projects/xal.txt

 :lang: en
 
 ############################################
-XAL - Execution abstraction layer for Python
+xal - Execution abstraction layer for Python
 ############################################
 
-* https://github.com/benoitbryon/xal
+`xal`_ is an experimental project that brings high-level portable system
+scripts to Python.
+
+You develop functions which take a session object as argument. The session
+object encapsulates implementation of system's resources: files, processes,
+packages...
+
+Xal has many use cases: provisioning, sysadmin scripts, portable shell
+doctests, ... It could be used to develop scripts that run in fabric, salt,
+buildout, shell...
+
+I created Xal.
+
+I'm to present it via a poster sessions at EuroPython 2013 in Florence, Italy.
+
+
+.. rubric:: References
+
+.. target-notes::
+
+.. _`xal`: https://github.com/benoitbryon/xal

File en/talks/index.txt

 Talks
 #####
 
-.. toctree::
-   :titlesonly:
+* "Diecutter: templates as a service",
+  a poster session for
+  EuroPython 2013, Florence, Italy
 
+* "XAL: execution abstraction layer",
+  a poster session for
+  EuroPython 2013, Florence, Italy
+
+* "WriteTheDocs.org: Sphinx documentation toolkit",
+  a poster session for
+  EuroPython 2013, Florence, Italy
+
+* "Don't fear the buildout",
+  a lightning-talk
+  at DjangoCon-Toulouse 2012
+
+* .. lang:: fr
+
+     "Valorisez votre documentation"
+     un lightning-talk
+     à DjangoCon-Toulouse 2012
+
+* .. lang:: fr
+
+     "Django et la traduction de données"
+     une conférence
+     à DjangoCong-Marseille 2010

File fr/articles/canaliser-les-flux-de-communication.txt

 ###################################
 Canaliser les flux de communication
 ###################################
-Conseils pour optimiser la communication au sein d'une équipe
-#############################################################
+
+.. epigraph:: Conseils pour optimiser la communication au sein d'une équipe.
 
 Dans cet article, j'essaie de partager des observations à propos informations
 échangées au sein d'une équipe, et de suggérer des recettes pour mieux en tirer
 
 .. note::
 
-  Cet article est une version volontairement simplifiée (et plus digeste) de
-  l'`article du même nom sur makina-corpus.org`_.
+   Cet article est une version volontairement simplifiée (et plus digeste) de
+   l'`article du même nom sur makina-corpus.org`_.
+
 
 **************
 Un cas d'école
 
 .. sourcecode:: irc
 
-  <Paul>  Je viens en renfort sur le projet, par ou est-ce que je commence ?
-  <Stephane>  Je t'envoie toutes les informations par e-mail.
+   <Paul>  Je viens en renfort sur le projet, par ou est-ce que je commence ?
+   <Stephane>  Je t'envoie toutes les informations par e-mail.
 
 Qui n'a jamais eu ce genre de conversation ? C'est malheureusement un cas
 d'école de choses à éviter :
 
 * malgré ses bonnes intentions, Stéphane va oublier quelque chose, ou bien se
   tromper ;
+
 * ce qu'il corrigera dans d'autres e-mails, après qu'un problème eût été
   détecté ;
+
 * dans 6 mois il sera très difficile de retrouver ces informations ;
+
 * si tous les membres de l'équipe partent, alors la connaissance est perdue
   en même temps que leurs archives e-mail ;
+
 * et bien d'autres désagréments...
 
 Des exemples comme celui-ci, on en rencontre beaucoup au cours de notre travail
 d'information de leur entreprise. Et s'il n'y en a pas, ce serait une bonne
 occasion d'en créer un.
 
+
 ***************************************
 Cet article n'est pas une documentation
 ***************************************
 * il a donc vocation à être obsolète, partial, incomplet...
 * ... j'essaye d'en tenir compte en le rédigeant, utilisez-le comme tel ;)
 
+
 ***********************************
 Caractériser les flux d'information
 ***********************************
 dans les canaux de production, dans la mesure où cela ne nuit pas à la qualité
 du produit.
 
+
 ***********************************
 Exemples de canaux de communication
 ***********************************
   => Versionné, décentralisé, au moins un dépôt de backup.
 
 Documentation "projet"
-  Voir l'`article à propos de la documentation projet`_.
+  Voir l':doc:`article à propos de la documentation projet <documentation>`.
 
   => Versionnée avec le code source, au format texte (RST, markdown), exportée
   dans d'autres formats (HTML) pour une consultation plus aisée.
 Contacts
   => Utiliser un service d'annuaire. Éviter l'échange de contacts par e-mail.
 
+
 ***************************
 Orienter les communications
 ***************************
 * privilégier les actions à forte valeur ajoutée, plutôt que de consacrer le
   principal de l'activité à suivre des procédures.
 
-**********
-Références
-**********
+
+.. rubric:: Références
 
 .. target-notes:: 
 
-.. _`article du même nom sur makina-corpus.org`: http://www.makina-corpus.org/blog/canaliser-les-flux-de-communication
-.. _`article à propos de la documentation projet`: http://www.marmelune.net/fr/documentation/
-.. _`"Une équipe remarquable au quotidien" lors de l'agile tour 2011 à Bordeaux`: http://www.makina-corpus.org/blog/travailler-en-%C3%A9quipe-des-efforts-au-quotidien
+.. _`article du même nom sur makina-corpus.org`:
+   http://www.makina-corpus.org/blog/canaliser-les-flux-de-communication
+.. _`"Une équipe remarquable au quotidien" lors de l'agile tour 2011 à
+   Bordeaux`:
+   http://www.makina-corpus.org/blog/travailler-en-%C3%A9quipe-des-efforts-au-quotidien

File fr/articles/django-reverse-lazy.txt

 ##############
 reverse_lazy()
 ##############
-Quand django.core.urlresolvers.reverse() n'est pas applicable
-#############################################################
 
+.. epigraph:: Quand django.core.urlresolvers.reverse() n'est pas applicable.
+
+
+*********
 Prérequis
-=========
+*********
 
 Afin d'aller à l'essentiel, je ne prendrai pas le temps d'expliciter toutes les 
 notions utilisées dans cet article. Aussi, si vous êtes mal à l'aise avec l'un 
 .. _`les "décorateurs" Python`: http://www.gawel.org/howtos/python-decorators
 .. _`le décorateur @login_required`: http://docs.djangoproject.com/en/1.2/topics/auth/#the-login-required-decorator
 
+
+*********
 reverse()
-=========
+*********
 
 Dans le framework Django, la fonction reverse() 
 (django.core.urlresolvers.reverse pour être exact) est importante. La 
 .. _`documentation Django à propos de reverse()`: http://docs.djangoproject.com/en/1.2/topics/http/urls/#reverse
 
 Résumé du problème
-------------------
+==================
 
 La fonction reverse() effectue une recherche dans les URLconf de Django. Plus 
 précisément, elle fait une recherche dans un objet URLResolver. Ce dernier  
 .. _`django.core.handlers.base.BaseHandler.get_response()`: http://code.djangoproject.com/browser/django/tags/releases/1.2.3/django/core/handlers/base.py#L66
 
 reverse() dans les URLconf
---------------------------
+==========================
 
 Premier cas facile à appréhender : que se passe-t-il si on souhaite utiliser 
 reverse() dans une URLconf ?
 un paramètre obligatoire, "url". Étant donné qu'il est hors de question 
 d'utiliser l'URL directement, on a besoin de reverse().
 
-TODO: ajouter un exemple (code) avec l'exception générée
-
 reverse() dans les decorateurs de vues
---------------------------------------
+======================================
 
 C'est, d'après mon expérience personnelle, le cas le plus courant.
 
 qui est une URL. Pas question d'indiquer l'URL réelle. Alors on a besoin de 
 reverse().
 
-TODO: ajouter un exemple (code), avec l'exception générée
-
 Pour bien comprendre pourquoi on ne peut pas utiliser reverse() ici, il faut 
 savoir que pour construire le catalogue d'URLconf, Django importe les vues 
 qui y sont mentionnées. Cela provoque l'interprétation du code de ces modules, 
 appliqués aux vues à ce moment-là.
 
 reverse() à d'autres endroits
------------------------------
+=============================
 
 Quelques autres emplacements méritent une attention particulière :
 
 à reverse() n'est pas encapsulé dans un objet ou une fonction, le problème 
 peut apparaître.
 
+
+****************************
 reverse_lazy(): une solution
-============================
+****************************
 
 Une solution simple à mettre en oeuvre est d'utiliser reverse_lazy(). Cette 
 fonction n'est pas encore disponible en standard dans Django.
         """
         return LazyString(reverse, *args, **kwargs)
 
+
+**********************
 Solutions alternatives
-======================
+**********************
 
 Pour aller plus loin dans la réflexion, voici quelques hypothèses...
 Notez bien qu'à ce jour, je ne sais pas si elles se vérifient.
 
 reverse() dans les URLconf
---------------------------
+==========================
 
 Si les vues ne prenaient pas en argument des URL "réelles" mais les paramètres 
 permettant de les obtenir, le problème ne se poserait pas. En effet, la 
 * les paramètres à passer à cette méthode.
 
 reverse() dans les décorateurs de vues
---------------------------------------
+======================================
 
 On l'a évoqué, pour construire le catalogue d'URLconf, Django importe toutes 
 les vues qui y sont mentionnées.

File fr/articles/documentation.txt

 ####################
 Documenter un projet
 ####################
-Conseils pragmatiques pour la documentation d'un projet de développement web
-############################################################################
 
+.. epigraph::
+
+   Conseils pragmatiques pour la documentation d'un projet de développement web
+
+
+*********************
 Pourquoi documenter ?
-=====================
+*********************
 
 * mémoire
 * transmission de savoir
 * partage de pratiques, conventions
 
 Un investissement
------------------
+=================
 
 * anticiper
 
 * coût de changement réduit
 
 Référence asynchrone
---------------------
+====================
 
 * Contributeurs asynchrones peuvent utiliser la documentation comme canal de
   communication.
 
+
+********************
 Conditions de succès
-====================
+********************
 
 * synchronisée avec le code
 * relue, utilisée, maintenue...
 * nécessaire, suffisante, complète
 * légère, rapide à lire, facile d'accès. Limiter l'effet "lecture en diagonale"
 
-Conditions de succès, en pratique
----------------------------------
+En pratique :
 
 * La documentation fait partie de la definition of done (scrum)
 * La documentation est versionnée avec le code
   * limiter le copier-coller
   * limiter les erreurs humaines
 
+
+*********************************
 Documentation != référence unique
-=================================
+*********************************
 
 * D'autres références plus concrètes :
 
   * bonnes pratiques
   * motivations, vision
 
+
+*********************
 Pour qui documenter ?
-=====================
+*********************
 
 * équipe(s) de production
 * maintenance
 * support
 * ...
 
+
+**************************
 Une documentation unique ?
-==========================
+**************************
 
 * si besoin, plusieurs documentations
 * mais au moins un point d'entrée
 * pour tous ceux qui travaillent/utilisent un même projet
 
+
+*******
 Contenu
-=======
+*******
 
 * références, standards
 * spécificités du projet
 * spécifications
 * conventions, charte d'équipe
 
+
+***********
 Pas contenu
-===========
+***********
 
 * documenté ailleurs => liens
 * spécificités d'un déploiement => configuration locale, templates
 * liste de commandes => scripts
 
+
+*******************
 Exemple de sommaire
-===================
+*******************
 
 * architecture
 * backup-restore
 * testing
 
 Architecture
-------------
+============
 
 * architecture cible du projet
 * si possible, pas spécifique à un hébergement donné
 * une documentation d'architecture / déploiement du projet peut être séparée
 
 Backup-restore
---------------
+==============
 
 * liste des éléments à sauvegarder
 * outils fournis pour la sauvegarde et la restauration
 * procédure d'importation de données
 
 Configuration
--------------
+=============
 
 * paramètres de configuration
 * configuration par défaut
 * outils de configuration (templates)
 
 Conventions
------------
+===========
 
 * langue selon lecteurs et rédacteurs
 * conventions de codage
 * charte d'équipe
 
 Documentation
--------------
+=============
 
 * outils de documentation
 * export de la documentation
 * conventions dans la documentation
 
 HISTORY
--------
+=======
 
 * historique des changemements et releases
 * lié à l'outil de versionning
 
+
+************************
 Documentation VS scripts
-========================
+************************
 
 * INSTALL.txt c'est nécessaire. Les procédures doivent être documentées.
 * install.sh c'est mieux.
 
 * documentation efficace = code est documentation + documentation succincte
 
+
+*********************
 Documentation VS code
-=====================
+*********************
 
 * Le code est lisible, commenté
 * Les commandes ont une documentation intégrée (man, --help...)
 
+
+************************
 Outils (trêve de blabla)
-========================
+************************
 
 * Export de la documentation :
 

File fr/articles/organisation-repertoires-projet-deploiement.txt

 :lang: fr
+:date: 2011-12-15
 
 ##############################
 Comment organiser ses fichiers
 ##############################
-Organisation de répertoires pour le développement et déploiement d'un projet
-############################################################################
 
-:date: 2011-12-15
-:lang: fr
-:tags: buildout git hg déploiement architecture infrastructure bootstrap
+.. epigraph::
+
+   Organisation de répertoires pour le développement et déploiement d'un
+   projet.
 
 Si vous avez réalisé plusieurs projets de développement web, vous vous êtes
 certainement aperçu que vous gagnez à utiliser toujours la même structure de