Izmantojiet Sfinksu, lai sistēmā CentOS 7 izveidotu dokumentāciju vairākos formātos

Sphinx ir noderīgs Python rīks tehniķiem un rakstniekiem, kas ļauj viegli izveidot elegantu, pilnībā funkcionējošu dokumentāciju dažādos formātos. Izmantojot Sphinx, jūs rakstāt dokumentus, izmantojot reStructuredText — vieglu iezīmēšanas valodu — iesācējiem varat iegūt izvadi vairākos formātos, tostarp HTML, LaTeX, PDF, ePub un citos.

Šajā apmācībā mēs apskatīsim SphinxCentOS 7 x64 instances instalēšanas un lietošanas procesu Vult platformā.

Priekšnoteikumi

• CentOS 7 x64 instance.
• Sudo lietotāju .

1. darbība: atjauniniet sistēmu

sudo yum update
sudo shutdown -r now

2. darbība: instalējiet pip un Sphinx

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

3. darbība. Iestatiet dokumentācijas pamata konfigurāciju

Pirms sākat lietot Sphinx, jums jānorāda avota direktorijs, kurā Sphinxdarbosies, un jāsaglabā visa jūsu dokumentācija. Kad esat izveidojis direktoriju, kuru plānojat izmantot, varat palaist, sphinx-quickstartkas inicializēs Sphinxun izveidos nepieciešamo pamata konfigurāciju.

sphinx-quickstart ir līdzīgs iestatīšanas vednim, kas uzdos jums jautājumus, kas nosaka jūsu projekta aspektus.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

4. darbība. Izveidojiet savas dokumentācijas hierarhiju

Pēc noklusējuma sphinx-quickstartvednis izveidos vairākus direktorijus un failus.

_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

Apskatīsim galveno failu index.rst, kurā ir jūsu dokumentācijas hierarhija; proti, satura rādītāja koks vai toctree.

Atveriet to ar teksta redaktoru:

vi index.rst

Pārskatot failu, jūs pamanīsit sadaļu ar nosaukumu toctree. Ja *.rstjūsu dokumentācijai ir citi avota faili ( ), tie būs jānorāda toctreesadaļā: .. toctree:: :maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Obligāti ir:

• Virs ievades atstājiet tukšu rindu.
• Nepievienojiet avota failiem sufiksu ar .rst.
• Ievietojiet avota failus to attiecīgajā secībā.
• Katrā rindā izmantojiet tikai vienu faila nosaukumu.
• Atkāpiet failu nosaukumus ar :maxdepth: 2.

Kad esat pabeidzis izmaiņas, saglabājiet failu un izejiet no teksta redaktora.

ESC
:!wq

5. darbība. Izveidojiet iepriekš norādītos avota failus

Avota faili ir jāizveido ar nosaukumiem, kas atbilst iepriekš norādītajam index.rst, pretējā gadījumā tie netiks iekļauti galīgajā izvadē.

Visiem avota failiem ir jābūt saderīgiem ar reStructuredText markup language. Lai iegūtu papildinformāciju, lūdzu, skatiet reStructuredText Primer .

6. darbība. Izvadiet savas dokumentācijas HTML versiju

Kad esat pabeidzis dokumentācijas sastādīšanu, varat izvadīt savu darbu HTML format , izpildot tālāk norādīto komandu:

make html

Izvade tiks saglabāta direktorijā, ./\_build/htmlkurā ir viss nepieciešamais faila apskatei tīmekļa pārlūkošanā.

Ar to mūsu apmācība ir beigusies.