Használja a Sphinxet dokumentumok létrehozásához több formátumban a CentOS 7 rendszeren

A Sphinx egy hasznos Python-alapú eszköz technikusok és írók számára, amely lehetővé teszi számukra, hogy könnyen készítsenek elegáns, teljesen működőképes dokumentációt különféle formátumokban. A Sphinx segítségével először a reStructuredText – egy könnyű jelölőnyelv – használatával írhat dokumentumokat, majd több formátumban is megkaphatja a kimenetet, beleértve a HTML-t, a LaTeX-et, a PDF-t, az ePub-ot és másokat.

Ebben az oktatóanyagban bemutatjuk Sphinxa CentOS 7 x64 példányok telepítésének és használatának folyamatát a Vult platformján.

Előfeltételek

• Egy CentOS 7 x64 példány.
• Egy sudo felhasználó .

1. lépés: Frissítse a rendszert

sudo yum update
sudo shutdown -r now

2. lépés: Telepítse a pip-et és a Sphinxet

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

3. lépés: Állítsa be a dokumentáció alapkonfigurációját

A használat megkezdése előtt Sphinxmeg kell adnia a forráskönyvtárat, amelyben Sphinxfutni fog, és el kell mentenie az összes dokumentációt. Miután létrehozta a használni kívánt könyvtárat, futtassa, sphinx-quickstartamely inicializálja Sphinxés létrehozza a szükséges alapkonfigurációt.

sphinx-quickstart hasonló egy telepítővarázslóhoz, amely olyan kérdéseket tesz fel, amelyek meghatározzák a projekt szempontjait.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

4. lépés: Építse fel a dokumentáció hierarchiáját

Alapértelmezés szerint a sphinx-quickstartvarázsló több könyvtárat és fájlt hoz létre.

_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

Vessünk egy pillantást a főfájlra index.rst, amely a dokumentáció hierarchiáját tartalmazza; mégpedig a tartalomjegyzék fa ill toctree.

Nyissa meg egy szövegszerkesztővel:

vi index.rst

A fájl áttekintése során észrevesz egy szakaszt, melynek neve toctree. Ha van más forrásfájlja ( *.rst) a dokumentációjához, akkor ezeket meg kell adnia a következő toctreerészben: .. toctree:: :maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Feltétlenül szükséges:

• Hagyjon egy üres sort a bevitel felett.
• A forrásfájlok utótagja ne legyen .rst.
• Helyezze el a forrásfájlokat a megfelelő sorrendbe.
• Soronként csak egy fájlnevet használjon.
• A fájlneveket húzza be a -val :maxdepth: 2.

Miután befejezte a módosításokat, mentse el a fájlt, és lépjen ki a szövegszerkesztőből.

ESC
:!wq

5. lépés: Hozzon létre fent megadott forrásfájlokat

A forrásfájlokat olyan nevekkel kell létrehozni, amelyek megegyeznek a korábban megadottakkal index.rst, különben nem kerülnek be a végső kimenetbe.

Minden forrásfájlnak kompatibilisnek kell lennie a reStructuredText markup language. További információkért tekintse meg a reStructuredText Primert .

6. lépés: Adja ki a dokumentáció HTML-verzióját

Miután befejezte a dokumentáció összeállítását, HTML format az alábbi parancs végrehajtásával kiadhatja a munkáját :

make html

A kimenet egy könyvtárba kerül elmentésre, ./\_build/htmlamely mindent tartalmaz, ami a fájl webböngészés közbeni megtekintéséhez szükséges.

Ezzel az oktatóanyagunk véget is ér.