1.1. Configurar un Server de Sphinx Auto-Doc

1.1.1. Configuración Inicial

Primero necesitará instalar los pre-requisitos de Python y crear el venv (ambiente virtual / virtual environment).

$ apt install python3 python3-pip python3-venv python3-virtualenv
$ mkdir sphinx
$ cd sphinx
$ virtualenv -p python3 .

Truco

Si no va a utilizar el Tema de PyData para Sphinx, no necesitará instalarlo, aún así, lo recomiendo!

Los temas Book y Read The Docs son buenas alternativas.

Ahora active su virtual environment e instale los complementos de Sphinx que quiera usar. Nuestros recomendados son los siguientes:

$ source bin/activate
$ pip3 install sphinx
$ pip3 install sphinx-copybutton # This is a pretty good extension

# THEMES TO INSTALL - INSTALL RTD IF AUTHOR BUG IS PRESENT
## READ THE DOCS THEME
$ pip3 install sphinx-rtd-theme
## BOOK THEME
$ pip3 install sphinx-book-theme
## PYDATA THEME (THE ONE THIS PAGE USES)
$ pip3 install pydata-sphinx-theme

Una vez eso esté hecho puede proceder a crear su propio sitio de Sphinx.

Generalmente querrá sub-dividirlo en directorios para mejor organización, pero antes de eso generemos el proyecto.

Vaya al directorio de trabajo en el que quiere hacerlo e introduzca los siguientes comandos

$ sphinx-quickstart

Usualmente estará bien usando la configuración pre-determinada, aunque yo habilité algunas extensiones.

Nota

No olvide cambiar la carpeta del proyecto y su path absoluto en el archivo conf.py

Ahora podemos ajustar el archivo de configuración para Sphinx

# Uncomment the lines below

import os
import sys
# sys.path.insert(0, os.path.abspath('/opt/sphinx'))

# TODAY Format
today_fmt = '%Y/%m/%d - %H:%M'

# You might also want to add this extension to give the site nice appearance, or search for another to your liking on the Sphinx Themes Site

extensions = [
"sphinx_copybutton",
"pydata_sphinx_theme",  # Disable if not used
"sphinx_rtd_theme",     # Disable if not used
"sphinx_book_theme",    # Disable if not used
]

Truco

If you wish to print out the latest update on an RST File use |today| on the rst file

También añadí archivos .md para ser legibles por el conf.py

source_suffix = ['.rst', '.md']

Una vez todo esto esté hecho puede probar la compilación

# Manual Build Command
$ sphinx-build -b html source/ build/

# Using Sphinx Quickstart's Makefile
$ make html

El sitio debería compilar en el sub-directorio build/html

Truco

Puede hacer un enlace simbólico para evitar copiar el sitio al apache todo el tiempo.

$ ln -s /opt/sphinx/build /var/www/sphinx

Truco

Quizá quiera borrar todos los archivos en su directorio build siempre que re-compile el sitio, ya que podría no re-indexar correctamente los tocs.

1.1.3. Configurar el Tema Read The Docs

Añada el siguiente bloque de código a su archivo conf.py:

html_theme_options = {
    # ----------------- RTD THEME
    'logo_only': True,
    'display_version': True,
    'prev_next_buttons_location': 'both',
    'collapse_navigation': False,
    'titles_only': False,
}

1.1.4. Configurar el Tema PyData

Para configurar el Tema de PyData tendrá que hacer algunos cambios a los siguientes archivos:
  • conf.py (En su directorio de sources o la raíz del proyecto)

  • gettext.py (En la carpeta lib/python3.x/site-packages/sphinx/builders/gettext.py dentro de su proyecto)

En su archivo conf.py añada:

Advertencia

No olvide cambiar el 3.x a la versión de Python de su Proyecto

# Add any paths that contain templates here, relative to this directory.
templates_path = [
    'lib/python3.x/site-packages/sphinx_book_theme/_templates',
    'lib/python3.x/site-packages/pydata_sphinx_theme/_templates',
    '_templates',
]

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
        "sphinx_copybutton",
        "pydata_sphinx_theme",
        "sphinx_rtd_theme",
        "sphinx_book_theme",
]

html_theme_options = {
    'logo_link': '',
    # ----------------- PYDATA THEME
    "use_edit_page_button": False,
    'collapse_navigation': False, # This is for PyData Theme
    'show_prev_next': False,
    "icon_links": [
        # {
        #     "name": "GitLab",
        #     "url": "",
        #     "icon": "fab fa-gitlab",
        # },
        {
            "name": "PyData Sphinx Theme",
            "url": "https://pydata-sphinx-theme.readthedocs.io/",
            "icon": "fas fa-brush",
        },
        {
            "name": "Twitter",
            "url": "",
            "icon": "fab fa-twitter-square",
        }
    ],
    "external_links": [
        {"name": "Your Website", "url": "https://localhost"}
    ]
}

Y en su archivo gettext.py, busque la clase GettextRenderer(SphinxRenderer) y añada:

def escape(s: str) -> str:
    #### This conditional is being added ####
    if s is None:
        return ""
    #########################################
    s = s.replace('\\', r'\\')
    s = s.replace('"', r'\"')
    return s.replace('\n', '\\n"\n"')

1.1.5. Añadir Archivos CSS propios

Añada el siguiente bloque de código a su conf.py:

html_css_files = [
    'css/style.css',
    'css/fonts.css'
]