Verwenden Sie Sphinx, um unter CentOS 7 eine Dokumentation in mehreren Formaten zu erstellen

• Voraussetzungen
• Schritt 1: Aktualisieren Sie das System
• Schritt 2: Installieren Sie Pip und Sphinx
• Schritt 3: Richten Sie die Grundkonfiguration für Ihre Dokumentation ein
• Schritt 4: Erstellen Sie die Hierarchie für Ihre Dokumentation
• Schritt 5: Erstellen Sie die oben angegebenen Quelldateien
• Schritt 6: Geben Sie die HTML-Version Ihrer Dokumentation aus

Sphinx ist ein nützliches Python-basiertes Tool für Techniker und Autoren, mit dem sie auf einfache Weise elegante, voll funktionsfähige Dokumentationen in verschiedenen Formaten erstellen können. Mit Sphinx schreiben Sie Dokumente zunächst mit reStructuredText - einer einfachen Markup-Sprache - und können dann die Ausgabe in verschiedenen Formaten abrufen, darunter HTML, LaTeX, PDF, ePub und andere.

In diesem Tutorial werden wir den Prozess der Installation und Verwendung Sphinxauf einer CentOS 7 x64-Instanz auf der Vult-Plattform behandeln.

Voraussetzungen

• Eine CentOS 7 x64-Instanz.
• Ein Sudo-Benutzer .

Schritt 1: Aktualisieren Sie das System

sudo yum update
sudo shutdown -r now

Schritt 2: Installieren Sie Pip und Sphinx

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

Schritt 3: Richten Sie die Grundkonfiguration für Ihre Dokumentation ein

Bevor Sie mit der Verwendung beginnen Sphinx, müssen Sie Ihr Quellverzeichnis angeben, in dem Sphinxdie gesamte Dokumentation ausgeführt und gespeichert werden soll. Nachdem Sie das Verzeichnis erstellt haben, das Sie verwenden möchten, können Sie es ausführen sphinx-quickstart, Sphinxum die erforderliche Grundkonfiguration zu initialisieren und zu erstellen.

sphinx-quickstart ähnelt einem Setup-Assistenten, der Sie mit Fragen auffordert, die die Aspekte Ihres Projekts bestimmen.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Schritt 4: Erstellen Sie die Hierarchie für Ihre Dokumentation

Standardmäßig erstellt der sphinx-quickstartAssistent mehrere Verzeichnisse und Dateien.

_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

Werfen wir einen Blick auf die Masterdatei index.rst, die die Hierarchie Ihrer Dokumentation enthält. nämlich das Inhaltsverzeichnis Baum oder toctree.

Öffnen Sie es mit einem Texteditor:

vi index.rst

Wenn Sie die Datei überprüfen, werden Sie einen Abschnitt mit dem Namen bemerken toctree. Wenn Sie andere Quelldateien ( *.rst) für Ihre Dokumentation haben, müssen Sie diese im toctreeAbschnitt angeben : .. toctree ::: maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Es ist unbedingt erforderlich:

• Lassen Sie eine leere Zeile über Ihrer Eingabe.
• Fügen Sie Ihren Quelldateien kein Suffix hinzu .rst.
• Platzieren Sie Ihre Quelldateien in der jeweiligen Reihenfolge.
• Verwenden Sie nur einen Dateinamen pro Zeile.
• Einrücken Sie Ihre Dateinamen mit :maxdepth: 2.

Wenn Sie Ihre Änderungen abgeschlossen haben, speichern Sie Ihre Datei und beenden Sie den Texteditor.

ESC
:!wq

Schritt 5: Erstellen Sie die oben angegebenen Quelldateien

Die Quelldateien müssen mit Namen erstellt werden, die mit den zuvor angegebenen übereinstimmen. index.rstAndernfalls werden sie nicht in die endgültige Ausgabe aufgenommen.

Alle Quelldateien müssen mit dem kompatibel sein reStructuredText markup language. Weitere Informationen finden Sie unter reStructuredText Primer .

Schritt 6: Geben Sie die HTML-Version Ihrer Dokumentation aus

Nachdem Sie Ihre Dokumentation erstellt haben, können Sie Ihre Arbeit ausgeben, HTML format indem Sie den folgenden Befehl ausführen:

make html

Die Ausgabe wird in dem Verzeichnis gespeichert, ./\_build/htmldas alles enthält, was zum Anzeigen der Datei in einem Webbrowser erforderlich ist.

Damit ist unser Tutorial abgeschlossen.