Gebruik Sphinx om documentatie te creëren in meerdere formaten op CentOS 7

• Vereisten
• Stap 1: werk het systeem bij
• Stap 2: Installeer pip en Sphinx
• Stap 3: Stel de basisconfiguratie in voor uw documentatie
• Stap 4: Construeer de hiërarchie voor uw documentatie
• Stap 5: Maak de hierboven gespecificeerde bronbestanden aan
• Stap 6: Voer de HTML-versie van uw documentatie uit

Sphinx is een handige op Python gebaseerde tool voor technici en schrijvers waarmee ze eenvoudig elegante, volledig functionele documentatie in verschillende formaten kunnen maken. Met Sphinx schrijft u documenten met behulp van reStructuredText - een lichtgewicht opmaaktaal - om te beginnen, waarna u de uitvoer in meerdere formaten kunt krijgen, waaronder HTML, LaTeX, PDF, ePub en andere.

In deze tutorial behandelen we het proces van installeren en gebruiken Sphinxop een CentOS 7 x64-instantie op het platform van Vult.

Vereisten

• Een CentOS 7 x64-exemplaar.
• Een sudo-gebruiker .

Stap 1: werk het systeem bij

sudo yum update
sudo shutdown -r now

Stap 2: Installeer pip en Sphinx

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

Stap 3: Stel de basisconfiguratie in voor uw documentatie

Voordat u begint te gebruiken Sphinx, moet u uw brondirectory specificeren waarin deze Sphinxzal worden uitgevoerd en al uw documentatie zal opslaan. Nadat u de directory hebt gemaakt die u wilt gebruiken, kunt u deze uitvoeren, sphinx-quickstartdie zal initialiseren Sphinxen de vereiste basisconfiguratie zal creëren.

sphinx-quickstart is vergelijkbaar met een installatiewizard die u vragen zal stellen die de aspecten van uw project bepalen.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Stap 4: Construeer de hiërarchie voor uw documentatie

Standaard maakt de sphinx-quickstartwizard verschillende mappen en bestanden.

_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

Laten we eens kijken naar het hoofdbestand index.rst, dat de hiërarchie van uw documentatie bevat; namelijk de inhoudsopgave boom of toctree.

Open het met een teksteditor:

vi index.rst

Terwijl u het bestand bekijkt, ziet u een sectie met de naam toctree. Als u andere bronbestanden ( *.rst) heeft voor uw documentatie, moet u deze specificeren in de toctreesectie: .. toctree ::: maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Het is absoluut noodzakelijk om:

• Laat een lege rij boven uw invoer.
• Geef uw bronbestanden geen achtervoegsel .rst.
• Plaats uw bronbestanden in hun respectievelijke volgorde.
• Gebruik slechts één bestandsnaam per rij.
• Laat uw bestandsnamen inspringen met :maxdepth: 2.

Nadat u uw wijzigingen heeft voltooid, slaat u uw bestand op en sluit u de teksteditor.

ESC
:!wq

Stap 5: Maak de hierboven gespecificeerde bronbestanden aan

De bronbestanden moeten worden gemaakt met namen die overeenkomen met wat eerder was gespecificeerd index.rst, anders worden ze niet opgenomen in de uiteindelijke uitvoer.

Alle bronbestanden moeten compatibel zijn met de reStructuredText markup language. Raadpleeg reStructuredText Primer voor meer informatie .

Stap 6: Voer de HTML-versie van uw documentatie uit

Als u klaar bent met het samenstellen van uw documentatie, kunt u uw werk HTML format uitvoeren door het onderstaande commando uit te voeren:

make html

De uitvoer wordt opgeslagen in de map ./\_build/htmldie alles bevat wat nodig is om het bestand te bekijken tijdens het surfen op het web.

Hiermee is onze tutorial afgesloten.