PyData Sphinx Theme

Uso, personlización y extensión

Jorge Martinez

@jorgepiloto

Documentación de NumPy

Documentación de Matplotlib

Documentación de SciPy

Documentación de Pandas

Documentación de Astropy

¿Qué es Sphinx?

  • Generador de documentación estática
  • Contenido escrito en rST o MyST
  • Renderiza en HTML, TeX, AsciiDoc y otros
  • Soporte para extensiones

Inicia un nuevo proyecto

Comienza instalando Sphinx:

python -m pip install sphinx

Inicia un nuevo proyecto:

sphinx-quickstart doc

doc/
├── build                # Directorio de salida
│   └── html
└── source               # Archivos fuente
    ├── _static          # CSS, JS, ...
    ├── _templates       # Plantillas
    ├── conf.py          # Configuración
    └── index.rst        # Pagina de inicio

El archivo conf.py

Metadatos, extensiones y otras configuraciones


# Metadata
project = 'MyProject'
copyright = '2024, Jorge Martinez'
author = 'Jorge Martinez'
release = '0.1.dev0'

# Extensiones
extensions = []
templates_path = ['_templates']
exclude_patterns = []

# Configuracion HTML
html_theme = 'alabaster'
html_static_path = ['_static']

El archivo index.rst

Archivo principal de la documentación


Docs de mi proyecto
===================

Bienvenidos a la documentación de mi proyecto. Aquí encontrarás toda la
información necesaria para poder utilizarlo. Puedes navegar por la
documentación y descubrir todas las funcionalidades que ofrece.

.. toctree::
   :maxdepth: 2

   getting-started
   user-guide
   api-reference
   examples

Renderizar y servir los docs

Indica la ruta de los archivos fuente y de salida junto con el formato deseado:

sphinx-build doc/source doc/build/html -b html

Sirve la documentación en local:

python -m http.server -d doc/build/html

Resultado

Instalación del PyData Sphinx Theme


Ejecuta:

python -m pip install pydata-sphinx-theme

Actívalo en el archivo de configuración:

html_theme = 'pydata_sphinx_theme'

Resultado

PyData Sphinx Theme Docs

Secciones y componentes

  • PyData Sphinx Theme contiene varios componentes
  • Los componentes pueden añadirse a las secciones
  • Los componentes pueden ser personalizados
  • La configuración se realiza en el archivo conf.py

Componentes por defecto: breadcrumbs, copyright, version-switcher, sphinx-version, navbar-icon-links, …

Body

Configuración


# Configuracion HTML

html_theme = 'pydata_sphinx_theme'

html_theme_options = {
    # Seccion: [component-A, component-B, ...]
    "navbar_end": ["navbar-icon-links"],
    "footer_start": [],
    "footer_center": ["copyright"],
    "footer_end": [],

    # Configuracion de componentes
    "icon_links": [
        # Utiliza los iconos de font-awesome brands
        dict(name="GitHub", url="...", icon="fab fa-github"),
        dict(name="LinkedIn", url="...", icon="fab fa-linkedin"),
    ],
}

Resultado

Código fuente de PST

theme/
└── pydata_sphinx_theme/
    ├── components/              # HTML de cada componente
    │   ├── breadcrumbs.html
    │   ├── copyright.html
    │   └── ...
    ├── layout.html              # HTML de la estructura global
    ├── search.html
    ├── sections/                # HTML de cada seccion
    │   ├── announcement.html
    │   ├── article.html
    │   ├── footer.html
    │   └── ...
    ├── static/                  # Archivos CSS y JS
    │   └── styles
    │       └── theme.css
    └── theme.conf               # Archivo theme.conf

El archivo theme.conf

Indica las variables permitidas en html_theme_options y las añade al contexto de Jinja con el prefijo theme.


[theme]
inherit = basic
stylesheet = styles/pydata-sphinx-theme.css
pygments_style = tango
sidebars = sidebar-nav-bs.html

[options]
...
use_edit_page_button = False
icon_links_label = Icon Links
icon_links =
show_prev_next = True
...

Original footer.html

Renderiza solo aquellas secciones del footer con componentes.

{% if theme_footer_start or theme_footer_center or theme_footer_end %}
<div class="bd-footer__inner bd-page-width">

  {% if theme_footer_start %}
    <div class="footer-items__start">
      {% for item in theme_footer_start %}
        <div class="footer-item">{% include item %}</div>
      {% endfor %}
    </div>
  {% endif %}

  ...

</div>
{% endif %}

Modificado footer.html

Sobreescribe el footer.html usando los doc/source/_templates/sections:

<div class="bd-footer__inner bd-page-width">
    <div class="footer-items__start">
        <div class="footer-item">
            <img src="{{ pathto('_static/loup.gif', 1) }}" />  
        </div>
    </div>
    ...
</div>

Resultado

Eventos de Sphinx

  • Son señales que Sphinx emite en ciertos puntos de su flujo de trabajo
  • Puedes realizar acciones específicas al capturarlos
  • Se capturan en la función setup del archivo conf.py
  • Lista de eventos

Algunos eventos: builder-inited, config-inited, source-read, missing-reference, warn-missing-reference, build-finished.

Ejemplo de gestión de eventos

Copiar contenido de la carpeta examples a la carpeta doc/source/examples antes de renderizar y eliminarlo después.


def copy_examples_to_doc_source(app):
    ...

def remove_examples_from_doc_source(app, exception):
    ...

def setup(app):
    app.connect('builder-inited', copy_examples_to_doc_source)
    app.connect('build-finished', remove_examples_from_doc_source)

PyAnsys

Interfaces de Python para los productos de Ansys.

https://docs.pyansys.com

Ejemplo: live search preview

Ejemplo: sphinx-autoapi