how - sphinx python example

¿Cómo agregar un archivo css personalizado a Sphinx?

Question

¿Cómo puedo agregar un archivo css personalizado? La siguiente configuración no funciona para mí:

# conf.py
html_static_path = [''_static'']
html_theme = ''default''
html_theme_options = {
  ''cssfiles'': [''_static/style.css'']
}

Resultado:

C:/temp/test-docs/docs>make html
Running Sphinx v1.2.2
loading pickled environment... not yet created
building [html]: targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
reading sources... [ 50%] help
reading sources... [100%] index

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents...
Theme error:
unsupported theme option ''cssfiles'' given

Answer 1

Debería poder incluir css personalizados al extender el tema de la esfinge por defecto. En su conf.py, especificaría dónde estaría su extensión al tema, como por ejemplo.

# Add any paths that contain templates here, relative to this directory.
templates_path = [''_templates'']

Luego, en _templates, crearía una extensión para el tema predeterminado llamado ''layout.html'' que incluiría sus archivos css como.

{# layout.html #}
{# Import the theme''s layout. #}
{% extends "!layout.html" %}

{% set css_files = css_files + [''_static/style.css''] %}

Consulte la documentación de sphinx sobre templating para obtener más información.

Answer 2

Las opciones que puede configurar a través de html_theme_options dependen del tema. Echa un vistazo a la sección [options] de theme.conf de tu tema para averiguar qué hay disponible.

Sin embargo, en una base global, puede definir html_context en su conf.py para anular la configuración de css_files (y, por lo demás, script_files también):

html_context = {
    ''css_files'': [''_static/custom.css''],
}

(Para referencia, eche un vistazo a los builders.html.StandaloneHTMLBuilder.prepare_writing() Sphinx y vea cómo se completa el self.globalcontext allí ).

Answer 3

Una forma más sencilla es agregar esto a su conf.py :

def setup(app):
    app.add_stylesheet(''css/custom.css'')  # may also be an URL

Luego ponga el archivo en la _static/css/ .