Kasutage CentOS 7-s mitmes vormingus dokumentatsiooni loomiseks Sphinxi

Sphinx on kasulik Pythonil põhinev tööriist tehnikutele ja kirjanikele, mis võimaldab neil hõlpsasti luua elegantset ja täisfunktsionaalset dokumentatsiooni erinevates vormingutes. Sphinxiga kirjutate dokumente alustuseks reStructuredTexti – kerge märgistuskeele – abil, seejärel saate väljundi mitmes vormingus, sealhulgas HTML, LaTeX, PDF, ePub ja teised.

Selles õpetuses käsitleme SphinxCentOS 7 x64 eksemplari installimise ja kasutamise protsessi Vulti platvormil.

Eeltingimused

• CentOS 7 x64 eksemplar.
• Sudo kasutaja .

1. samm: värskendage süsteemi

sudo yum update
sudo shutdown -r now

2. samm: installige pip ja Sphinx

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

3. samm: seadistage oma dokumentatsiooni põhikonfiguratsioon

Enne kasutamise alustamist Sphinxpeate määrama lähtekataloogi, kus Sphinxsee töötab, ja salvestama kogu teie dokumentatsiooni. Kui olete loonud kataloogi, mida kavatsete kasutada, saate käivitada, sphinx-quickstartmis lähtestab Sphinxja loob vajaliku põhikonfiguratsiooni.

sphinx-quickstart on sarnane häälestusviisardisega, mis esitab teile küsimusi, mis määravad teie projekti aspektid.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

4. samm: koostage oma dokumentatsiooni hierarhia

Vaikimisi sphinx-quickstartloob viisard mitu kataloogi ja faili.

_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

Vaatame põhifaili index.rst, mis sisaldab teie dokumentatsiooni hierarhiat; nimelt sisukorrapuu või toctree.

Avage see tekstiredaktoriga:

vi index.rst

Faili üle vaadates märkate jaotist nimega toctree. Kui teil on dokumentatsiooni jaoks muid lähtefaile ( *.rst), peate need määrama toctreejaotises: .. toctree:: :maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

See on hädavajalik:

• Jätke sisendi kohale tühi rida.
• Ärge lisage lähtefailide järelliidet .rst.
• Asetage lähtefailid nende vastavas järjekorras.
• Kasutage rea kohta ainult ühte failinime.
• Failinimede taane tõmmake :maxdepth: 2.

Kui olete muudatused lõpetanud, salvestage fail ja väljuge tekstiredaktorist.

ESC
:!wq

5. samm: looge ülaltoodud lähtefailid

Lähtefailid tuleb luua nimedega, mis ühtivad varem failis määratuga index.rst, vastasel juhul ei kaasata neid lõppväljundisse.

Kõik lähtefailid peavad ühilduma failiga reStructuredText markup language. Lisateabe saamiseks vaadake reStructuredText Primer .

6. samm: väljastage oma dokumentatsiooni HTML-versioon

Kui olete dokumentide koostamise lõpetanud, saate oma töö väljastada HTML format , täites alloleva käsu:

make html

Väljund salvestatakse kataloogi, ./\_build/htmlmis sisaldab kõike vajalikku faili vaatamiseks veebisirvimisel.

Sellega meie õpetus lõpeb.