Përdorni Sphinx për të krijuar dokumentacion në formate të shumta në CentOS 7

Sphinx është një mjet i dobishëm i bazuar në Python për teknikët dhe shkrimtarët që u lejon atyre të krijojnë me lehtësi dokumentacion elegant, plotësisht funksional në formate të ndryshme. Me Sphinx, ju shkruani dokumente duke përdorur reStructuredText -- një gjuhë e lehtë shënjimi -- për fillestarët, më pas mund të merrni rezultatin në formate të shumta, duke përfshirë HTML, LaTeX, PDF, ePub dhe të tjerë.

Në këtë tutorial, ne do të mbulojmë procesin e instalimit dhe përdorimit Sphinxnë një shembull CentOS 7 x64 në platformën e Vult.

Parakushtet

• Një shembull CentOS 7 x64.
• Një përdorues sudo .

Hapi 1: Përditësoni sistemin

sudo yum update
sudo shutdown -r now

Hapi 2: Instaloni pip dhe Sphinx

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

Hapi 3: Vendosni konfigurimin bazë për dokumentacionin tuaj

Përpara se të filloni të përdorni Sphinx, duhet të specifikoni direktorinë tuaj burimore në të cilën Sphinxdo të ekzekutohet dhe do të ruhet i gjithë dokumentacioni juaj. Pasi të keni krijuar direktorinë që keni ndërmend të përdorni, më pas mund të ekzekutoni e sphinx-quickstartcila do të inicializojë Sphinxdhe krijojë konfigurimin bazë të kërkuar.

sphinx-quickstart është i ngjashëm me një magjistar konfigurimi i cili do t'ju nxisë me pyetje që përcaktojnë aspektet e projektit tuaj.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Hapi 4: Ndërtoni hierarkinë për dokumentacionin tuaj

Si parazgjedhje, sphinx-quickstartmagjistari do të krijojë disa drejtori dhe skedarë.

_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

Le t'i hedhim një sy skedarit master, index.rst, i cili përmban hierarkinë e dokumentacionit tuaj; domethënë, pema e tabelës së përmbajtjes ose toctree.

Hapeni atë me një redaktues teksti:

vi index.rst

Ndërsa rishikoni skedarin, do të vini re një seksion të quajtur toctree. Nëse keni skedarë të tjerë burimor ( *.rst) për dokumentacionin tuaj, do t'ju duhet t'i specifikoni në toctreeseksionin: .. toctree:: :maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Është e domosdoshme që:

• Lini një rresht bosh mbi të dhënat tuaja.
• Mos vendosni prapashtesën e skedarëve tuaj burimor me .rst.
• Vendosni skedarët tuaj burimor sipas renditjes së tyre përkatëse.
• Përdorni vetëm një emër skedari për rresht.
• Shënoni emrat e skedarëve tuaj me :maxdepth: 2.

Pasi të keni përfunduar modifikimet tuaja, ruani skedarin tuaj dhe dilni nga redaktori i tekstit.

ESC
:!wq

Hapi 5: Krijoni skedarë burimi të specifikuar më sipër

Skedarët burim duhet të krijohen me emra që përputhen me atë që ishte specifikuar më parë në index.rst, përndryshe ato nuk do të përfshihen në daljen përfundimtare.

Të gjithë skedarët burim duhet të jenë të pajtueshëm me reStructuredText markup language. Për më shumë informacion, ju lutemi referojuni reStructuredText Primer .

Hapi 6: Nxjerr versionin HTML të dokumentacionit tuaj

Pasi të keni mbaruar përpilimin e dokumentacionit tuaj, mund të nxirrni punën tuaj HTML format duke ekzekutuar komandën e mëposhtme:

make html

Dalja do të ruhet në drejtorinë e ./\_build/htmlcila përfshin gjithçka të nevojshme për shikimin e skedarit në një shfletim në internet.

Kjo përfundon tutorialin tonë.