Utilizați Sphinx pentru a crea documentație în mai multe formate pe CentOS 7

• Cerințe preliminare
• Pasul 1: Actualizați sistemul
• Pasul 2: Instalați pip și Sphinx
• Pasul 3: Configurați configura��ia de bază pentru documentația dvs.
• Pasul 4: Construiți ierarhia pentru documentația dvs.
• Pasul 5: Creați fișiere sursă specificate mai sus
• Pasul 6: Executați versiunea HTML a documentației dvs.

Sphinx este un instrument util bazat pe Python pentru tehnicieni și scriitori care le permite să creeze cu ușurință documentație elegantă, complet funcțională, în diferite formate. Cu Sphinx, scrieți documente folosind reStructuredText - un limbaj de marcare ușor - pentru început, apoi puteți obține ieșirea în mai multe formate, inclusiv HTML, LaTeX, PDF, ePub și altele.

În acest tutorial, vom acoperi procesul de instalare și utilizare Sphinxpe o instanță CentOS 7 x64 pe platforma Vult.

Cerințe preliminare

• O instanță CentOS 7 x64.
• Un utilizator sudo .

Pasul 1: Actualizați sistemul

sudo yum update
sudo shutdown -r now

Pasul 2: Instalați pip și Sphinx

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

Pasul 3: Configurați configurația de bază pentru documentația dvs.

Înainte de a începe utilizarea Sphinx, trebuie să specificați directorul sursă în care Sphinxva rula și să salvați toată documentația. După ce ați creat directorul pe care intenționați să-l utilizați, puteți rula apoi sphinx-quickstartcare va inițializa Sphinxși crea configurația de bază necesară.

sphinx-quickstart este similar cu un vrăjitor de configurare care vă va solicita întrebări care determină aspectele proiectului.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Pasul 4: Construiți ierarhia pentru documentația dvs.

În mod implicit, sphinx-quickstartexpertul va crea mai multe directoare și fișiere.

_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

Să aruncăm o privire asupra fișierului principal index.rst, care conține ierarhia documentației dvs.; și anume, arborele de conținut sau toctree.

Deschide-l cu un editor de text:

vi index.rst

Când analizați fișierul, veți observa o secțiune apelată toctree. Dacă aveți alte fișiere sursă ( *.rst) pentru documentația dvs., va trebui să le specificați în toctreesecțiunea: .. toctree ::: maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Este obligatoriu să:

• Lasă un rând gol deasupra intrării tale.
• Nu sufixați fișierele sursă cu .rst.
• Plasați fișierele sursă în ordinea respectivă.
• Utilizați un singur nume de fișier pe rând.
• Indentificați numele fișierelor cu :maxdepth: 2.

După ce ați finalizat modificările, salvați fișierul și ieșiți din editorul de text.

ESC
:!wq

Pasul 5: Creați fișiere sursă specificate mai sus

Fișierele sursă trebuie create cu nume care se potrivesc cu cele specificate anterior index.rst, în caz contrar nu vor fi incluse în ieșirea finală.

Toate fișierele sursă trebuie să fie compatibile cu reStructuredText markup language. Pentru mai multe informații, consultați reStructuredText Primer .

Pasul 6: Executați versiunea HTML a documentației dvs.

După ce ați terminat să vă redactați documentația, puteți să vă efectuați lucrările HTML format executând comanda de mai jos:

make html

Ieșirea va fi salvată în directorul ./\_build/htmlcare include tot ceea ce este necesar pentru vizualizarea fișierului într-o navigare web.

Acest lucru încheie tutorialul nostru.