Använd Sphinx för att skapa dokumentation i flera format på CentOS 7

Sphinx är ett användbart Python-baserat verktyg för tekniker och skribenter som gör att de enkelt kan skapa elegant, fullt fungerande dokumentation i olika format. Med Sphinx skriver du dokument med hjälp av reStructuredText – ett lättviktigt märkningsspråk – till att börja med, sedan kan du få utdata i flera format, inklusive HTML, LaTeX, PDF, ePub och andra.

I den här handledningen kommer vi att täcka processen att installera och använda Sphinxpå en CentOS 7 x64-instans på Vults plattform.

Förutsättningar

• En CentOS 7 x64-instans.
• En sudo-användare .

Steg 1: Uppdatera systemet

sudo yum update
sudo shutdown -r now

Steg 2: Installera pip och Sphinx

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

Steg 3: Ställ in den grundläggande konfigurationen för din dokumentation

Innan du börjar använda Sphinxmåste du ange din källkatalog som Sphinxska köras och spara all din dokumentation. När du har skapat katalogen du tänker använda kan du sedan köra sphinx-quickstartsom kommer att initiera Sphinxoch skapa den nödvändiga grundläggande konfigurationen.

sphinx-quickstart liknar en installationsguide som ger dig frågor som avgör aspekterna av ditt projekt.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Steg 4: Konstruera hierarkin för din dokumentation

Som standard sphinx-quickstartskapar guiden flera kataloger och filer.

_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

Låt oss ta en titt på huvudfilen, index.rst, som innehåller hierarkin för din dokumentation; nämligen innehållsförteckningsträdet eller toctree.

Öppna den med en textredigerare:

vi index.rst

När du granskar filen kommer du att märka ett avsnitt som heter toctree. Om du har andra källfiler ( *.rst) för din dokumentation, måste du ange dem i toctreeavsnittet: .. toctree:: :maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Det är absolut nödvändigt att:

• Lämna en tom rad ovanför din inmatning.
• Suffix inte dina källfiler med .rst.
• Placera dina källfiler i deras respektive ordning.
• Använd endast ett filnamn per rad.
• Dra in dina filnamn med :maxdepth: 2.

När du har slutfört dina ändringar, spara din fil och avsluta textredigeraren.

ESC
:!wq

Steg 5: Skapa källfiler som anges ovan

Källfilerna måste skapas med namn som matchar det som tidigare angivits i index.rst, annars kommer de inte att inkluderas i den slutliga utdata.

Alla källfiler måste vara kompatibla med reStructuredText markup language. För mer information, se reStructuredText Primer .

Steg 6: Mata ut HTML-versionen av din dokumentation

När du har skrivit klart din dokumentation kan du mata ut ditt arbete HTML format genom att utföra kommandot nedan:

make html

Utdata kommer att sparas i katalogen ./\_build/htmlsom innehåller allt som behövs för att visa filen i en webbsurfning.

Detta avslutar vår handledning.