Utilisez Sphinx pour créer de la documentation dans plusieurs formats sur CentOS 7

• Conditions préalables
• Étape 1: mettre à jour le système
• Étape 2: installer pip et Sphinx
• Étape 3: Installez la configuration de base pour votre documentation
• Étape 4: Construisez la hiérarchie de votre documentation
• Étape 5: créer les fichiers source spécifiés ci-dessus
• Étape 6: sortie de la version HTML de votre documentation

Sphinx est un outil utile basé sur Python pour les techniciens et les écrivains qui leur permet de créer facilement une documentation élégante et pleinement fonctionnelle dans divers formats. Avec Sphinx, vous écrivez des documents en utilisant reStructuredText - un langage de balisage léger - pour les débutants, puis vous pouvez obtenir la sortie dans plusieurs formats, y compris HTML, LaTeX, PDF, ePub et autres.

Dans ce didacticiel, nous couvrirons le processus d'installation et d'utilisation Sphinxsur une instance CentOS 7 x64 sur la plate-forme Vult.

Conditions préalables

• Une instance CentOS 7 x64.
• Un utilisateur sudo .

Étape 1: mettre à jour le système

sudo yum update
sudo shutdown -r now

Étape 2: installer pip et Sphinx

sudo yum install -y python-devel python-setuptools python-pip
sudo pip install --upgrade pip
sudo pip install -U Sphinx

Étape 3: Installez la configuration de base pour votre documentation

Avant de commencer à utiliser Sphinx, vous devez spécifier votre répertoire source dans lequel Sphinxs'exécutera et enregistrer toute votre documentation. Une fois que vous avez créé le répertoire que vous avez l'intention d'utiliser, vous pouvez alors exécuter sphinx-quickstartce qui initialisera Sphinxet créera la configuration de base requise.

sphinx-quickstart est similaire à un assistant de configuration qui vous posera des questions qui détermineront les aspects de votre projet.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Étape 4: Construisez la hiérarchie de votre documentation

Par défaut, l' sphinx-quickstartassistant crée plusieurs répertoires et fichiers.

_build           # The directory for containing Sphinx output
conf.py          # The file containing your project configurations
index.rst        # The master file containing the hierarchy of your documentation
make.bat         # A Windows command file
Makefile         # A file necessary for running the make command
_static          # The directory for static files, including custom stylesheets, pictures, etc.
_templates       # The directory for custom templates

Jetons un œil au fichier maître index.rst, qui contient la hiérarchie de votre documentation; à savoir, l'arborescence de la table des matières ou toctree.

Ouvrez-le avec un éditeur de texte:

vi index.rst

En examinant le fichier, vous remarquerez une section intitulée toctree. Si vous avez d'autres fichiers sources ( *.rst) pour votre documentation, vous devrez les spécifier dans la toctreesection: .. toctree ::: maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Il est impératif de:

• Laissez une ligne vide au-dessus de votre entrée.
• Ne suffixez pas vos fichiers source avec .rst.
• Placez vos fichiers source dans leur ordre respectif.
• Utilisez un seul nom de fichier par ligne.
• Mettez en retrait vos noms de fichiers avec :maxdepth: 2.

Une fois vos modifications terminées, enregistrez votre fichier et quittez l'éditeur de texte.

ESC
:!wq

Étape 5: créer les fichiers source spécifiés ci-dessus

Les fichiers source doivent être créés avec des noms qui correspondent à ce qui était précédemment spécifié index.rst, sinon ils ne seront pas inclus dans la sortie finale.

Tous les fichiers source doivent être compatibles avec le reStructuredText markup language. Pour plus d'informations, veuillez vous reporter à l' amorce de reStructuredText .

Étape 6: sortie de la version HTML de votre documentation

Une fois que vous avez fini de composer votre documentation, vous pouvez sortir votre travail en HTML format exécutant la commande ci-dessous:

make html

La sortie sera enregistrée dans le répertoire ./\_build/htmlqui comprend tout le nécessaire pour visualiser le fichier dans une navigation Web.

Ceci conclut notre tutoriel.