Как добавить собственный файл CSS в Sphinx?

Как добавить пользовательский файл css? Следующая конфигурация не работает для меня:

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

Результат:

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

Ответы

Ответ 1

Проще всего добавить это в свой conf.py:

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

Затем поместите файл в папку _static/css/.

Ответ 2

Вы должны иметь возможность включить пользовательские CSS, расширив тему sphinx по умолчанию. В вашем conf.py вы указали бы, где будет ваше расширение к теме, например.

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

Затем в _templates вы создадите расширение для темы по умолчанию с именем layout.html, которое будет включать ваши cssfiles, например.

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

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

См. документацию sphinx по шаблонам для получения дополнительной информации.

Ответ 3

Параметры, которые вы можете настроить с помощью html_theme_options, зависят от темы. Ознакомьтесь с разделом [options] ваших тем theme.conf, чтобы узнать, что доступно.

Однако на глобальном уровне вы можете определить html_context в своем conf.py, чтобы переопределить настройки для css_files (и, если на то пошло, script_files тоже):

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

(Для справки, посмотрите Sphinxs builders.html.StandaloneHTMLBuilder.prepare_writing() и посмотрите как там заселяется self.globalcontext.)