PyData Sphinx Theme

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, …

Header

Note

Los componentes de la seccion navbar_persistent no colapsan en dispositivos pequeños; siempre se muestran.

Body

Footer

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)

PyData Sphinx Theme

Documentación de NumPy

Documentación de Matplotlib

Documentación de SciPy

Documentación de Pandas

Documentación de Astropy

¿Qué es Sphinx?

Inicia un nuevo proyecto

El archivo `conf.py`

El archivo `index.rst`

Renderizar y servir los docs

Resultado

Instalación del PyData Sphinx Theme

Resultado

PyData Sphinx Theme Docs

Secciones y componentes

Header

Body

Footer

Configuración

Resultado

Código fuente de PST

El archivo `theme.conf`

Original `footer.html`

Modificado `footer.html`

Resultado

Eventos de Sphinx

Ejemplo de gestión de eventos

PyAnsys

Ejemplo: live search preview

Ejemplo: sphinx-autoapi