Käytä Sphinxiä dokumentaation luomiseen useissa muodoissa CentOS 7:ssä

Sphinx on hyödyllinen Python-pohjainen työkalu teknikoille ja kirjoittajille, jonka avulla he voivat helposti luoda tyylikästä, täysin toimivaa dokumentaatiota eri muodoissa. Sphinxin avulla kirjoitat asiakirjoja reStructuredTextillä – kevyellä merkintäkielellä – aluksi, minkä jälkeen voit saada tulosteen useissa muodoissa, mukaan lukien HTML, LaTeX, PDF, ePub ja muut.

Tässä opetusohjelmassa käsittelemme SphinxCentOS 7 x64 -esiintymän asentamista ja käyttöä Vultin alustalla.

Edellytykset

• CentOS 7 x64 -esiintymä.
• Sudo käyttäjä .

Vaihe 1: Päivitä järjestelmä

sudo yum update
sudo shutdown -r now

Vaihe 2: Asenna pip ja Sphinx

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

Vaihe 3: Määritä dokumentaation perusasetukset

Ennen kuin aloitat käytön Sphinx, sinun on määritettävä lähdehakemisto, jossa Sphinxse suoritetaan, ja tallennettava kaikki dokumentaatiosi. Kun olet luonut käytettävän hakemiston, voit suorittaa sen, sphinx-quickstartjoka alustaa Sphinxja luo tarvittavat perusasetukset.

sphinx-quickstart on samanlainen kuin ohjattu asennustoiminto, joka kysyy kysymyksiä, jotka määrittävät projektisi näkökohdat.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Vaihe 4: Luo dokumentaatiosi hierarkia

Oletuksena sphinx-quickstartohjattu toiminto luo useita hakemistoja ja tiedostoja.

_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

Katsotaanpa päätiedostoa index.rst, joka sisältää dokumentaatiosi hierarkian; eli sisällysluettelopuu tai toctree.

Avaa se tekstieditorilla:

vi index.rst

Kun tarkastelet tiedostoa, huomaat osion nimeltä toctree. Jos sinulla on muita lähdetiedostoja ( *.rst) dokumentaatiota varten, sinun on määritettävä ne toctreekohdassa: .. toctree:: :maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

On välttämätöntä:

• Jätä syötteesi yläpuolelle tyhjä rivi.
• Älä liitä lähdetiedostosi päätteeksi .rst.
• Sijoita lähdetiedostot vastaavaan järjestykseen.
• Käytä vain yhtä tiedostonimeä riviä kohden.
• Sisennä tiedostojen nimet :maxdepth: 2.

Kun olet tehnyt muutokset, tallenna tiedosto ja poistu tekstieditorista.

ESC
:!wq

Vaihe 5: Luo yllä määritellyt lähdetiedostot

Lähdetiedostot on luotava nimillä, jotka vastaavat sitä, mitä aiemmin määritettiin index.rst, muuten niitä ei sisällytetä lopulliseen tuotteeseen.

Kaikkien lähdetiedostojen on oltava yhteensopivia reStructuredText markup language. Lisätietoja on artikkelissa reStructuredText Primer .

Vaihe 6: Lähetä asiakirjojen HTML-versio

Kun olet valmis laatimaan dokumentaatiosi, voit tulostaa työsi HTML format suorittamalla alla olevan komennon:

make html

Tulos tallennetaan hakemistoon, ./\_build/htmljoka sisältää kaiken tarvittavan tiedoston katseluun verkkoselailussa.

Tämä päättää opetusohjelmamme.