Sphinx – Tema minimalista, sin JS.

Estoy tratando de hacer funcionar un tema muy minimalista para Sphinx. Mi objetivo principal con Sphinx es utilizarlo para compartir manuales o conjuntos de instrucciones (incluyendo fragmentos de código) con colegas y estudiantes.

Mi interés en él comenzó hace algún tiempo, cuando siguiendo un curso en Udemy impartido por Colt Steele, me fascinó la documentación que compartió como parte del curso. El resultado es limpio, muy portable y fácil de compartir.

La estructura de carpetas es bastante minimalista, como esta como ejemplo:

. ├── .buildinfo ├── _images │ ├── cards.gif │ └── jokes.png ├── _static │ ├── graphviz.css │ ├── handouts-sphinx.css │ ├── my.css │ └── pygments.css └── index.html

Entonces, solo el archivo html más el css y los medios indispensables. Sin js.

Sin embargo, mi resultado, sin importar cuán poco contenido tenga, es mucho más grande después de ejecutar make html.

Supongo que esto se debe a la presencia de las funcionalidades de búsqueda y navegación incorporadas (¡que me gustaría saber cómo eliminar!), pero de todos modos realmente muchos archivos:

├── _sources │ └── index.rst.txt ├── _static │ ├── basic.css │ ├── check-solid.svg │ ├── clipboard.min.js │ ├── copy-button.svg │ ├── copybutton.css │ ├── copybutton.js │ ├── copybutton_funcs.js │ ├── doctools.js │ ├── documentation_options.js │ ├── file.png │ ├── jquery-3.5.1.js │ ├── jquery.js │ ├── language_data.js │ ├── minus.png │ ├── plus.png │ ├── pygments.css │ ├── searchtools.js │ ├── sphinx_press_theme.css │ ├── theme.css │ ├── theme.js │ ├── underscore-1.13.1.js │ └── underscore.js ├── genindex.html ├── index.html ├── objects.inv └── search.html

Entonces, mi pregunta finalmente es:

¿Cómo puedo producir un tema para obtener una compilación más liviana como la de Colt Steele con solo el archivo html y el css/imagenes?

Solo necesito la navegación básica de anclaje dentro de ese único archivo html, sin búsqueda, sin páginas “prev” o “next”.

¿Cómo puedo lograr una compilación así?

Aquí tienes una captura de pantalla del archivo html del primer árbol para ilustrar lo sencillo que es:
Enlace a la captura de pantalla

davy.ai

July 22, 2023 at 4:57 pm

Para lograr una estructura simplificada como la de Colt Steele, puedes crear un tema personalizado para Sphinx que elimine las funcionalidades de búsqueda y navegación incorporadas. Para hacer esto, deberás crear un nuevo directorio de temas en tu proyecto Sphinx y modificar el archivo layout.html.

Primero, crea un nuevo directorio para tu tema en el directorio /_themes. Llámalo minimal.

En el directorio minimal, crea un nuevo archivo llamado layout.html. Este archivo se utilizará como la plantilla principal para tu construcción de Sphinx.

En layout.html, puedes eliminar cualquier elemento no deseado, como la barra de búsqueda y los enlaces de navegación. También puedes eliminar archivos JavaScript innecesarios.

Aquí tienes un ejemplo de archivo layout.html para un tema minimalista:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <title>{{ title }}</title>
        <link rel="stylesheet" href="{{ pathto('_static/my.css', 1) }}">
        <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}">
    </head>
    <body>
        <header>
            <h1>{{ project }}</h1>
        </header>

        <div class="body">
            {{ body }}
        </div>

        <footer>
            Generado utilizando Sphinx
        </footer>
    </body>
</html>

Esta plantilla incluye el nombre del proyecto, el contenido principal y un pie de página con información sobre la construcción de Sphinx.

Una vez que hayas creado tu tema personalizado, puedes especificarlo en el archivo conf.py de Sphinx estableciendo la opción html_theme con el nombre de tu directorio de temas:

html_theme = 'minimal'

Con tu nuevo tema y configuración en su lugar, ejecuta nuevamente make html para regenerar tu salida Sphinx. Esta vez, la salida solo debería contener un archivo HTML y los archivos CSS y multimedia necesarios.

Answer

davy.ai

July 22, 2023 at 4:57 pm
Para lograr una estructura simplificada como la de Colt Steele, puedes crear un tema personalizado para Sphinx que elimine las funcionalidades de búsqueda y navegación incorporadas. Para hacer esto, deberás crear un nuevo directorio de temas en tu proyecto Sphinx y modificar el archivo layout.html.

Primero, crea un nuevo directorio para tu tema en el directorio /_themes. Llámalo minimal.

En el directorio minimal, crea un nuevo archivo llamado layout.html. Este archivo se utilizará como la plantilla principal para tu construcción de Sphinx.

En layout.html, puedes eliminar cualquier elemento no deseado, como la barra de búsqueda y los enlaces de navegación. También puedes eliminar archivos JavaScript innecesarios.

Aquí tienes un ejemplo de archivo layout.html para un tema minimalista:
```
<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <title>{{ title }}</title>
        <link rel="stylesheet" href="{{ pathto('_static/my.css', 1) }}">
        <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}">
    </head>
    <body>
        <header>
            <h1>{{ project }}</h1>
        </header>

        <div class="body">
            {{ body }}
        </div>

        <footer>
            Generado utilizando Sphinx
        </footer>
    </body>
</html>
```
Esta plantilla incluye el nombre del proyecto, el contenido principal y un pie de página con información sobre la construcción de Sphinx.

Una vez que hayas creado tu tema personalizado, puedes especificarlo en el archivo conf.py de Sphinx estableciendo la opción html_theme con el nombre de tu directorio de temas:
```
html_theme = 'minimal'
```
Con tu nuevo tema y configuración en su lugar, ejecuta nuevamente make html para regenerar tu salida Sphinx. Esta vez, la salida solo debería contener un archivo HTML y los archivos CSS y multimedia necesarios.

Comments are closed.

es.davy.ai

¿Tienes una pregunta?

Sphinx – Tema minimalista, sin JS.

Answer

davy.ai