Naudokite „Sfinksą“, kad sukurtumėte dokumentaciją keliais formatais „CentOS 7“.

„Sfinksas“ yra naudingas „Python“ pagrindu sukurtas įrankis, skirtas technikai ir rašytojams, leidžiantis lengvai kurti elegantišką, visiškai funkcionalią įvairių formatų dokumentaciją. Naudodami Sphinx galite rašyti dokumentus naudodami reStructuredText – lengvą žymėjimo kalbą – pradedantiesiems, tada galite gauti išvestį keliais formatais, įskaitant HTML, LaTeX, PDF, ePub ir kitus.

Šiame vadove apžvelgsime Sphinx„CentOS 7 x64“ egzemplioriaus „Vult“ platformoje diegimo ir naudojimo procesą .

Būtinos sąlygos

• CentOS 7 x64 egzempliorius.
• Sudo vartotojas .

1 veiksmas: atnaujinkite sistemą

sudo yum update
sudo shutdown -r now

2 veiksmas: įdiekite pip ir Sphinx

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

3 veiksmas: nustatykite pagrindinę dokumentacijos konfigūraciją

Prieš pradėdami naudoti Sphinx, turite nurodyti šaltinio katalogą, kuriame Sphinxbus paleista, ir išsaugoti visą dokumentaciją. Sukūrę katalogą, kurį ketinate naudoti, galite paleisti, sphinx-quickstartkuris inicijuos Sphinxir sukurs reikiamą pagrindinę konfigūraciją.

sphinx-quickstart yra panašus į sąrankos vedlį, kuris užduos klausimus, kurie nulems jūsų projekto aspektus.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

4 veiksmas: sukurkite savo dokumentų hierarchiją

Pagal numatytuosius nustatymus sphinx-quickstartvedlys sukurs kelis katalogus ir 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

Pažvelkime į pagrindinį failą index.rst, kuriame yra jūsų dokumentų hierarchija; būtent turinio medis arba toctree.

Atidarykite jį naudodami teksto rengyklę:

vi index.rst

Peržiūrėdami failą pastebėsite skyrių pavadinimu toctree. Jei turite kitų šaltinio failų ( *.rst) savo dokumentacijai, turėsite juos nurodyti toctreeskyriuje: .. toctree:: :maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Būtina:

• Virš įvesties palikite tuščią eilutę.
• Nenaudokite šaltinio failų priedėlio su .rst.
• Sudėkite šaltinio failus atitinkama tvarka.
• Vienoje eilutėje naudokite tik vieną failo pavadinimą.
• Įtraukite failų pavadinimus naudodami :maxdepth: 2.

Atlikę pakeitimus, išsaugokite failą ir išeikite iš teksto rengyklės.

ESC
:!wq

5 veiksmas: sukurkite pirmiau nurodytus šaltinio failus

Šaltinio failai turi būti sukurti su pavadinimais, kurie atitinka tuos, kurie anksčiau buvo nurodyti index.rst, kitaip jie nebus įtraukti į galutinę išvestį.

Visi šaltinio failai turi būti suderinami su reStructuredText markup language. Norėdami gauti daugiau informacijos, žr. reStructuredText Primer .

6 veiksmas: išveskite dokumentacijos HTML versiją

Baigę kurti dokumentus, galite išvesti savo darbą HTML format vykdydami toliau pateiktą komandą:

make html

Išvestis bus išsaugota kataloge, ./\_build/htmlkuriame yra viskas, ko reikia norint peržiūrėti failą naršant internete.

Tai baigia mūsų mokymo programą.