Koristite Sphinx za izradu dokumentacije u više formata na CentOS 7

Sphinx je koristan alat temeljen na Pythonu za tehničare i pisce koji im omogućuje jednostavno stvaranje elegantne, potpuno funkcionalne dokumentacije u različitim formatima. Sa Sphinxom pišete dokumente koristeći reStructuredText – lagani jezik za označavanje – za početak, a zatim možete dobiti izlaz u više formata, uključujući HTML, LaTeX, PDF, ePub i druge.

U ovom vodiču ćemo pokriti proces instaliranja i korištenja Sphinxna instanci CentOS 7 x64 na Vultovoj platformi.

Preduvjeti

• Instanca CentOS 7 x64.
• Korisnik sudoa .

Korak 1: Ažurirajte sustav

sudo yum update
sudo shutdown -r now

Korak 2: Instalirajte pip i Sphinx

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

Korak 3: Postavite osnovnu konfiguraciju za svoju dokumentaciju

Prije nego počnete koristiti Sphinx, morate navesti svoj izvorni direktorij u koji Sphinxće se izvoditi i spremati sva vaša dokumentacija. Nakon što ste stvorili direktorij koji namjeravate koristiti, možete pokrenuti sphinx-quickstartkoji će inicijalizirati Sphinxi stvoriti potrebnu osnovnu konfiguraciju.

sphinx-quickstart sličan je čarobnjaku za postavljanje koji će vam postaviti pitanja koja određuju aspekte vašeg projekta.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Korak 4: Izgradite hijerarhiju za svoju dokumentaciju

Prema zadanim postavkama, sphinx-quickstartčarobnjak će stvoriti nekoliko direktorija i datoteka.

_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

Pogledajmo glavnu datoteku index.rst, koja sadrži hijerarhiju vaše dokumentacije; naime, stablo sadržaja ili toctree.

Otvorite ga u uređivaču teksta:

vi index.rst

Dok pregledavate datoteku, primijetit ćete odjeljak pod nazivom toctree. Ako imate druge izvorne datoteke ( *.rst) za svoju dokumentaciju, morat ćete ih navesti u toctreeodjeljku: .. toctree:: :maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Imperativ je:

• Ostavite prazan red iznad unosa.
• Ne stavljajte sufiks vašim izvornim datotekama s .rst.
• Postavite izvorne datoteke njihovim redoslijedom.
• Koristite samo jedan naziv datoteke po retku.
• Uvucite nazive datoteka s :maxdepth: 2.

Nakon što dovršite svoje izmjene, spremite datoteku i izađite iz uređivača teksta.

ESC
:!wq

Korak 5: Stvorite izvorne datoteke navedene gore

Izvorne datoteke moraju biti kreirane s nazivima koji odgovaraju onome što je prethodno navedeno u index.rst, inače neće biti uključene u konačni izlaz.

Sve izvorne datoteke moraju biti kompatibilne s reStructuredText markup language. Za više informacija pogledajte reStructuredText Primer .

Korak 6: Iznesite HTML verziju svoje dokumentacije

Nakon što završite sa sastavljanjem svoje dokumentacije, možete izvesti svoj rad HTML format izvršavanjem donje naredbe:

make html

Izlaz će biti spremljen u direktorij ./\_build/htmlkoji uključuje sve što je potrebno za pregledavanje datoteke u web pregledavanju.

Ovim je naš vodič završen.