Full Circle Magazine FR

Cette page est en lecture seule. Vous pouvez afficher le texte source, mais ne pourrez pas le modifier. Contactez votre administrateur si vous pensez qu'il s'agit d'une erreur.
**Sphinx is a very nice document processor; it can create html, latex, pdf’s, and more. I started using it a few years ago to write a short book about Wood Turning. The reason for choosing Sphinx is its ability to create the different styles by creating only a config file and writing the document in reStructuredText. Here is the documentation: http://docutils.sourceforge.net/rst.html 

If you have not used markup, you are missing out. Try it out. All you need it an editor such as vim/gvim or ??? – your choice – do not use a word processor.  So here is the basic layout for the markup and how to install Sphinx (by the way, Sphinx was written to create Python documentation).**

Sphinx est une excellente application de mise en page de document : il peut créer du html, du latex, des pdf et plus encore. J'ai commencé à l'utiliser il y a quelques années pour écrire un court livre sur le bois tourné (Wood Turning). La raison pour laquelle j'ai choisi Sphinx est sa capacité à créer différents styles en ne créant qu'un fichier config et en écrivant le texte dans reStructuredText. Voici la documentation : http://docutils.sourceforge.net/rst.html

Si vous n'avez pas utilisé markup, vous manquez quelque chose. Essayez-le. Tout ce dont vous avez besoin est un éditeur tel que vim/gvim ou ??? - à votre choix - n'utilisez pas de traitement de texte. Voici la disposition de base pour markup et comment installer Sphinx (d'ailleurs, Sphinx a été écrit pour réaliser la documentation de Python).

**This was copied  from the Sphinx documentation page: http://www.sphinx-doc.org/en/stable/
• Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text
• Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information
• Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
• Automatic indices: general index as well as a language-specific module indices
• Code handling: automatic highlighting using the Pygments highlighter
• Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and
• Contributed extensions: more than 50 extensions contributed by users in a second repository; most of them installable from PyPI**

Ceci a été traduit à partir de la page de documentation de Sphinx : http://www.sphinx-doc.org/en/stable/
• Formats de sortie : HTML ( y compris l'aide HTML de Windows), LaTeX (pour les versions imprimables en PDF), ePub, Texinfo, pages de manuel, texte brut.
• Références croisées étendues : markup sémantique et liens automatiques pour les fonctions, classes, citations, termes du glossaire et éléments d'information similaires.
• Structure hiérarchique : définition facile de l'arborescence du document, avec des liens automatiques vers les frères, parents et enfants.
• Indices automatiques : un index général tout comme des index pour les modules spécifiques à un langage.
• Gestion du code : surlignage automatique utilisant le surligneur Pygments.
• Extensions : test automatique de segments du code, inclusion de docstrings à partir de modules en Python (API docs) et
• Extensions de la communauté : plus de 50 extensions dues à la contribution des utilisateurs dans un second dépôt, la plupart d'entre elles installables depuis PyPI.


**OK, let’s install Python and Sphinx; most distributions come with Python installed or at least in the package manager. You may still need to install PyPi to use pip:

sudo apt install python-pip

Install Sphinx, either from a distribution package or from PyPi

$ pip install Sphinx

or

sudo apt install python-sphinx

this works best for Ubuntu 16.04.01

Then run and answer all questions, be sure to say yes to autodoc extensions. If you want to create a directory first and change to that dir, quickstart will do it for you:

$ sphinx-quickstart

After this is finished, you will have a index.rst file that looks like this, and you will have a conf.py file created from the questions you answered in the quickstart.**

Bon ! Installons Python et Sphinx ; la plupart des distributions arrivent avec Python installé ou au moins dans le gestionnaire de paquets. Vous devrez peut-être installer PyPI pour pouvoir utiliser pip :

sudo apt install python-pip

Installez Sphinx, soit depuis le paquet de la distribution soit par PyPi :

$ pip install Sphinx

ou

sudo apt install python-sphinx

Ceci fonctionne mieux pour Ubuntu 16.04.01.

Puis lancez et répondez à toutes les questions ; assurez-vous de dire « oui » aux extensions autodoc. Si vous voulez créer d'abord un répertoire et changer pour ce répertoire, quickstart le fera pour vous :

$ sphinx-quickstart

Après avoir fini ceci, vous aurez un fichier index.rst qui ressemblera à ceci et vous aurez un fichier conf.py créé à partir des réponses aux questions de quickstart :

** 
:maxdepth: 2
 
   intro
   tutorial
 
Just add your chapters etc into this file as shown in the example at the bottom of the previous page.

You may want to look through the conf.py file and see if it is what you want, if not make the changes. Then type:

make html

This will build the documentation you just created in html format under the _build/html directory. If you make for other types of files, you will see the directories created in the _build dir. Example:

doctrees  html  latex  tex  xml

I hope this is of use to some people who like to try new ways of using Ubuntu/Linux.**

:maxdepth: 2
 
   intro
   tutorial

Ajoutez simplement vos chapitres, etc., dans ce fichier comme montré dans l'exemple du bas de la page précédente.

Vous souhaiterez peut-être regarder dans le fichier conf.py pour voir si c'est ce que vous voulez ; si ce n'est pas le cas, faites les modifications. Puis tapez :

make html

Ceci construira au format html la documentation que vous venez de créer, dans le répertoire _build/html. Si vous voulez faire d'autres types de fichiers, vous verrez les répertoires créés dans le dossier _build. Exemple :

doctrees  html  latex  tex  xml

J'espère que tout ceci sera utile aux personnes qui aiment essayer de nouvelles façons d'utiliser Ubuntu/Linux.