Uporabite Sphinx za ustvarjanje dokumentacije v več formatih v CentOS 7

Sphinx je uporabno orodje, ki temelji na Pythonu za tehnike in pisce, ki jim omogoča preprosto ustvarjanje elegantne, popolnoma funkcionalne dokumentacije v različnih formatih. S Sphinxom pišete dokumente z uporabo reStructuredText – lahkega označevalnega jezika – za začetek, nato pa lahko dobite izhod v več oblikah, vključno s HTML, LaTeX, PDF, ePub in drugimi.

V tej vadnici bomo pokrivali postopek namestitve in uporabe Sphinxna primerku CentOS 7 x64 na platformi Vult.

Predpogoji

• Primerek CentOS 7 x64.
• Uporabnik sudo .

1. korak: Posodobite sistem

sudo yum update
sudo shutdown -r now

2. korak: Namestite pip in Sphinx

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

3. korak: Nastavite osnovno konfiguracijo za vašo dokumentacijo

Preden začnete uporabljati Sphinx, morate določiti izvorni imenik, v katerem se Sphinxbo izvajala in shranila vsa vaša dokumentacija. Ko ustvarite imenik, ki ga nameravate uporabiti, lahko zaženete, sphinx-quickstartki bo inicializiral Sphinxin ustvaril zahtevano osnovno konfiguracijo.

sphinx-quickstart je podoben čarovniku za namestitev, ki vas bo pozval z vprašanji, ki določajo vidike vašega projekta.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

4. korak: zgradite hierarhijo za vašo dokumentacijo

sphinx-quickstartČarovnik bo privzeto ustvaril več imenikov in datotek.

_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

Oglejmo si glavno datoteko index.rst, ki vsebuje hierarhijo vaše dokumentacije; in sicer drevo kazala oz toctree.

Odprite ga z urejevalnikom besedil:

vi index.rst

Ko pregledujete datoteko, boste opazili razdelek z imenom toctree. Če imate druge izvorne datoteke ( *.rst) za svojo dokumentacijo, jih boste morali navesti v toctreerazdelku: .. toctree:: :maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Nujno je treba:

• Pustite prazno vrstico nad svojim vnosom.
• Ne dodajajte izvornih datotek s pripono .rst.
• Postavite svoje izvorne datoteke v ustreznem vrstnem redu.
• Uporabite samo eno ime datoteke na vrstico.
• Zamaknite imena datotek z :maxdepth: 2.

Ko končate s spremembami, shranite datoteko in zapustite urejevalnik besedil.

ESC
:!wq

5. korak: Ustvarite zgoraj navedene izvorne datoteke

Izvorne datoteke morajo biti ustvarjene z imeni, ki se ujemajo s tem, kar je bilo prej podano v index.rst, sicer ne bodo vključene v končni izhod.

Vse izvorne datoteke morajo biti združljive z reStructuredText markup language. Za več informacij si oglejte reStructuredText Primer .

6. korak: Iznesite različico HTML vaše dokumentacije

Ko končate s sestavljanjem svoje dokumentacije, lahko svoje delo izpišete HTML format tako, da izvedete spodnji ukaz:

make html

Izhod bo shranjen v imenik, ./\_build/htmlki vključuje vse potrebno za ogled datoteke med brskanjem po spletu.

S tem je naša vadnica zaključena.