Configurar un Server de Sphinx Auto-Doc

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 .

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 # Esta es una muy buena extensión

# TEMAS A INSTALAR - INSTALE RTD SI EL BUG DEL AUTOR SE PRESENTA
## TEMA READ THE DOCS
$ pip3 install sphinx-rtd-theme
## TEMA BOOK
$ pip3 install sphinx-book-theme
## TEMA PYDATA
$ 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 puede habilitar algunas extensiones.

Ahora podemos ajustar el archivo de configuración para Sphinx.

# Descomente las líneas debajo

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

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

extensions = [
"sphinx_copybutton",
"pydata_sphinx_theme",  # Des-habilitar si no se utiliza
"sphinx_rtd_theme",     # Des-habilitar si no se utiliza
"sphinx_book_theme",    # Des-habilitar si no se utiliza
]

# Versiones de Python soportadas para buildear los paths.
supported_python_versions = ["3.6","3.7","3.8","3.9"]

# Añadir directorios que contengan plantillas, relativas a este directorio.
templates_path = []
templates_path += [f'lib/python{v}/site-packages/sphinx_book_theme/_templates' for v in supported_python_versions]
templates_path += [f'lib/python{v}/site-packages/pydata_sphinx_theme/_templates' for v in supported_python_versions]
templates_path.append("_templates")

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.

# Comando de Compilación Manual
$ sphinx-build -b html source/ build/

# Utilizando el Makefile de Sphinx Quickstart
$ make html

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

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

Para añadir un Logo a su Proyecto Sphinx (si lo soporta el tema) añada la siguiente línea a su archivo conf.py:

# LOGO DEL TEMA
html_logo = 'logo.svg'

Luego añada su logo a la carpeta _static en la raíz de su proyecto o el directorio de sources.

Configurar el Tema Read The Docs

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

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

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:

# Versiones de Python Soportadas
supported_python_versions = ["3.6","3.7","3.8","3.9"]

# Añada los directorios con plantillas que quiera aquí, relativo a este directorio.
templates_path = []
templates_path += [f'lib/python{v}/site-packages/sphinx_book_theme/_templates' for v in supported_python_versions]
templates_path += [f'lib/python{v}/site-packages/pydata_sphinx_theme/_templates' for v in supported_python_versions]
templates_path.append("_templates")

# Añada cualquier módulo de extensión de Sphinx aquí como Strings.
extensions = [
    "sphinx_copybutton",
    "pydata_sphinx_theme",
    "sphinx_rtd_theme",
    "sphinx_book_theme",
]

html_theme_options = {
    'logo_link': '',
    # ----------------- TEMA PYDATA
    "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"')

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'
]
Last modified at Jun 9, 2023
Añadir contenido al Árbol TOC →