diff --git a/python/formation/docutils.txt b/python/formation/docutils.txt new file mode 100644 index 0000000..c09cb71 --- /dev/null +++ b/python/formation/docutils.txt @@ -0,0 +1,52 @@ +Sphinx et docutils +===================== + +Docutils +------------ + +Il y a des librairies de bas niveau qui permettent de générer de l'odt, je pense à pyUNO, ou bien ezodf_ + +.. _ezodf: https://pythonhosted.org/ezodf/ + +A l'opposé, il y a des librairies de très haut niveau intégré à des chaînes de documentation avec des sources en xml, des modèles documentaires, des chartes graphiques, etc. Par exemple, scenari_ + +.. _scenari: http://scenari-platform.org/projects/scenari/fr/pres/co/ + +Un juste milieu est la très intéressante librairie docutils_ : + +.. _docutils: http://docutils.sourceforge.net/ + +Il s'agit d'une libairie python très utilisée dans le monde python (par exemple, la documentation officielle python est rédigée en `syntaxe docutils`_). + +.. _`syntaxe docutils` : http://docutils.sourceforge.net/docs/index.html + +C'est une `syntaxe wiki`_ assez puissante, un sur-ensemble de la très connue syntaxe markdown. + +.. _`syntaxe wiki`: http://docutils.sourceforge.net/docs/user/rst/quickref.html + +Pour l'installer:: + + apt-get install python-docutils + +Il y a plusieurs utilitaires : ``rst2html``, ``rst2*``, l'utilitaire que je te conseille est : ``rst2odt``. + +Pour l'usage de `rst2odt`_ c'est simple, on part d'un fichier texte formaté en restructured text:: + + rst2odt fichier.txt > fichier.odt + +Et voilà simple, pratique, efficace. + +.. _`rst2odt`: http://docutils.sourceforge.net/docs/user/odt.html + +C'est l'outil que nous utilisons en priorité. Voici un exemple d'usage avancé avec l'utilisation d'un modèle:: + + rst2odt --create-links --file-insertion-enabled --raw-enabled --endnotes-end-doc \ + --stylesheet=styles/styles.odt --custom-odt-footer="XXXREMPLACEHEADERXXX" \ + DossierCommercial.rst > DossierCommercial.odt + +La documentation technique +----------------------------- + +L'outil sphinx_ + +.. _sphinx: http://sphinx-doc.org/ diff --git a/python/formation/getting-started.txt b/python/formation/getting-started.txt index 231c078..5a01019 100644 --- a/python/formation/getting-started.txt +++ b/python/formation/getting-started.txt @@ -7,7 +7,9 @@ L'objectif de ce cours est de vous apprendre à programmer en :term:`python`. Ce cours a été fait avec :term:`sphinx`, l'outil de gestion de documentation en python utilisé pour documenter python lui-même. -avec python : +Pour plus d'information : :doc:`docutils` + +Avec python : - vous n'avez pas grand chose à savoir pour arriver à faire beaucoup de choses, diff --git a/python/formation/index.txt b/python/formation/index.txt index 594638c..5f20199 100644 --- a/python/formation/index.txt +++ b/python/formation/index.txt @@ -10,7 +10,7 @@ Apprentissage de la programmation avec python type structures testsunitaires - + docutils Programmation python, connaissances de base --------------------------------------------