Use Sphinx para crear documentación en múltiples formatos en CentOS 7

• Prerrequisitos
• Paso 1: actualiza el sistema
• Paso 2: Instale pip y Sphinx
• Paso 3: configura la configuración básica para tu documentación
• Paso 4: construya la jerarquía para su documentación
• Paso 5: crea los archivos fuente especificados anteriormente
• Paso 6: envíe la versión HTML de su documentación

Sphinx es una herramienta útil basada en Python para técnicos y escritores que les permite crear fácilmente documentación elegante y completamente funcional en varios formatos. Con Sphinx, puede escribir documentos utilizando reStructuredText, un lenguaje de marcado ligero, para principiantes, luego puede obtener la salida en múltiples formatos, incluidos HTML, LaTeX, PDF, ePub y otros.

En este tutorial, cubriremos el proceso de instalación y uso Sphinxen una instancia de CentOS 7 x64 en la plataforma de Vult.

Prerrequisitos

• Una instancia de CentOS 7 x64.
• Un usuario de sudo .

Paso 1: actualiza el sistema

sudo yum update
sudo shutdown -r now

Paso 2: Instale pip y Sphinx

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

Paso 3: configura la configuración básica para tu documentación

Antes de comenzar a usar Sphinx, debe especificar su directorio de origen en el que Sphinxse ejecutará y guardará toda su documentación. Una vez que haya creado el directorio que pretende usar, puede ejecutar lo sphinx-quickstartque se inicializará Sphinxy creará la configuración básica requerida.

sphinx-quickstart es similar a un asistente de configuración que le hará preguntas que determinan los aspectos de su proyecto.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Paso 4: construya la jerarquía para su documentación

Por defecto, el sphinx-quickstartasistente creará varios directorios y archivos.

_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

Echemos un vistazo al archivo maestro index.rst, que contiene la jerarquía de su documentación; a saber, el árbol de tabla de contenido o toctree.

Ábrelo con un editor de texto:

vi index.rst

A medida que revise el archivo, notará una sección llamada toctree. Si tiene otros archivos fuente ( *.rst) para su documentación, deberá especificarlos en la toctreesección: .. toctree ::: maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Es imprescindible:

• Deje una fila en blanco encima de su entrada.
• No sufijas tus archivos fuente con .rst.
• Coloque sus archivos de origen en su orden respectivo.
• Use solo un nombre de archivo por fila.
• Sangra tus nombres de archivo con :maxdepth: 2.

Una vez que haya completado sus modificaciones, guarde su archivo y salga del editor de texto.

ESC
:!wq

Paso 5: crea los archivos fuente especificados anteriormente

Los archivos de origen deben crearse con nombres que coincidan con lo que se especificó anteriormente index.rst; de lo contrario, no se incluirán en la salida final.

Todos los archivos de origen deben ser compatibles con reStructuredText markup language. Para obtener más información, consulte reStructuredText Primer .

Paso 6: envíe la versión HTML de su documentación

Una vez que haya terminado de componer su documentación, puede generar su trabajo HTML format ejecutando el siguiente comando:

make html

La salida se guardará en el directorio ./\_build/htmlque incluye todo lo necesario para ver el archivo en una navegación web.

Esto concluye nuestro tutorial.