53 lines
1.9 KiB
Plaintext
53 lines
1.9 KiB
Plaintext
|
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/
|