Utilitzeu Sphinx per crear documentació en diversos formats a CentOS 7

Sphinx és una eina útil basada en Python per a tècnics i escriptors que els permet crear fàcilment documentació elegant i totalment funcional en diversos formats. Amb Sphinx, escriu documents amb reStructuredText, un llenguatge de marques lleuger, per començar, i després pots obtenir la sortida en diversos formats, inclosos HTML, LaTeX, PDF, ePub i altres.

En aquest tutorial, Sphinxcobrirem el procés d'instal·lació i ús en una instància CentOS 7 x64 a la plataforma de Vult.

Requisits previs

• Una instància CentOS 7 x64.
• Un usuari de sudo .

Pas 1: actualitzeu el sistema

sudo yum update
sudo shutdown -r now

Pas 2: instal·leu pip i Sphinx

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

Pas 3: configureu la configuració bàsica de la vostra documentació

Abans de començar a utilitzar Sphinx, heu d'especificar el vostre directori font on Sphinxs'executarà i desarà tota la documentació. Un cop hàgiu creat el directori que voleu utilitzar, podeu executar-lo sphinx-quickstartque s'inicializarà Sphinxi crearà la configuració bàsica necessària.

sphinx-quickstart és similar a un assistent de configuració que us demanarà preguntes que determinen els aspectes del vostre projecte.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Pas 4: construïu la jerarquia per a la vostra documentació

Per defecte, l' sphinx-quickstartassistent crearà diversos directoris i fitxers.

_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

Fem una ullada al fitxer mestre, index.rst, que conté la jerarquia de la vostra documentació; és a dir, l'arbre de la taula de continguts o toctree.

Obriu-lo amb un editor de text:

vi index.rst

Quan reviseu el fitxer, notareu una secció anomenada toctree. Si teniu altres fitxers font ( *.rst) per a la vostra documentació, haureu d'especificar-los a la toctreesecció: .. toctree:: :maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

És imprescindible:

• Deixeu una fila en blanc a sobre de la vostra entrada.
• No poseu un sufix als fitxers font amb .rst.
• Col·loqueu els fitxers font en el seu ordre respectiu.
• Utilitzeu només un nom de fitxer per fila.
• Sagna els noms dels fitxers amb :maxdepth: 2.

Un cop hàgiu completat les modificacions, deseu el fitxer i sortiu de l'editor de text.

ESC
:!wq

Pas 5: creeu els fitxers font especificats anteriorment

Els fitxers font s'han de crear amb noms que coincideixin amb el que s'ha especificat anteriorment a index.rst, en cas contrari no s'inclouran a la sortida final.

Tots els fitxers font han de ser compatibles amb el fitxer reStructuredText markup language. Per obtenir més informació, consulteu reStructuredText Primer .

Pas 6: emet la versió HTML de la documentació

Un cop hàgiu acabat de redactar la documentació, podeu enviar el vostre treball HTML format executant l'ordre següent:

make html

La sortida es desarà al directori ./\_build/htmlque inclou tot el necessari per visualitzar el fitxer en una navegació web.

Això conclou el nostre tutorial.