Commit fca7216b authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet
Browse files

docs: allow selecting a Sphinx theme 



Instead of having RTD as an almost mandatory theme, allow the
user to select other themes via DOCS_THEME environment var.

There's a catch, though: as the current theme override logic is
dependent of the RTD theme, we need to move the code which
adds the CSS overrides to be inside the RTD theme logic.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/bd20adabfd428fd3cd0e69c2cf146aa354932936.1638870323.git.mchehab+huawei@kernel.org


Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent b080e521

Documentation/Makefile

+3 −0
Original line number Original line Diff line number Diff line
@@ -19,6 +19,7 @@ endif 
SPHINXBUILD   = sphinx-build

SPHINXBUILD   = sphinx-build

SPHINXOPTS    =

SPHINXOPTS    =

SPHINXDIRS    = .

SPHINXDIRS    = .

DOCS_THEME    =

_SPHINXDIRS   = $(sort $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst)))

_SPHINXDIRS   = $(sort $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst)))

SPHINX_CONF   = conf.py

SPHINX_CONF   = conf.py

PAPER         =

PAPER         =
@@ -154,4 +155,6 @@ dochelp: 
	@echo  '  make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'

	@echo  '  make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'

	@echo  '  configuration. This is e.g. useful to build with nit-picking config.'

	@echo  '  configuration. This is e.g. useful to build with nit-picking config.'

	@echo

	@echo

	@echo '   make DOCS_THEME={sphinx-theme} selects a different Sphinx theme.'

	@echo

	@echo  '  Default location for the generated documents is Documentation/output'
 
	@echo  '  Default location for the generated documents is Documentation/output'

Documentation/conf.py

+30 −22
Original line number Original line Diff line number Diff line
@@ -208,16 +208,36 @@ highlight_language = 'none' 
# The theme to use for HTML and HTML Help pages.  See the documentation for

# The theme to use for HTML and HTML Help pages.  See the documentation for

# a list of builtin themes.

# a list of builtin themes.





# The Read the Docs theme is available from

# Default theme

# - https://github.com/snide/sphinx_rtd_theme

html_theme = 'sphinx_rtd_theme'

# - https://pypi.python.org/pypi/sphinx_rtd_theme



# - python-sphinx-rtd-theme package (on Debian)

if "DOCS_THEME" in os.environ:

    html_theme = os.environ["DOCS_THEME"]



if html_theme == 'sphinx_rtd_theme':

    # Read the Docs theme

    try:

    try:

        import sphinx_rtd_theme

        import sphinx_rtd_theme

    html_theme = 'sphinx_rtd_theme'

        html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

        html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]



        # Add any paths that contain custom static files (such as style sheets) here,

        # relative to this directory. They are copied after the builtin static files,

        # so a file named "default.css" will overwrite the builtin "default.css".

        html_css_files = [

            'theme_overrides.css',

        ]

    except ImportError:

    except ImportError:

    sys.stderr.write('Warning: The Sphinx \'sphinx_rtd_theme\' HTML theme was not found. Make sure you have the theme installed to produce pretty HTML output. Falling back to the default theme.\n')

        html_theme = 'classic'



if major <= 1 and minor < 8:

    html_context = {

        'css_files': [],

    }



    for l in html_css_files:

        html_context['css_files'].append('_static/' + l)



sys.stderr.write("Using %s theme\n" % html_theme)





# Theme options are theme-specific and customize the look and feel of a theme

# Theme options are theme-specific and customize the look and feel of a theme

# further.  For a list of options available for each theme, see the

# further.  For a list of options available for each theme, see the
@@ -246,20 +266,8 @@ except ImportError: 
# Add any paths that contain custom static files (such as style sheets) here,

# Add any paths that contain custom static files (such as style sheets) here,

# relative to this directory. They are copied after the builtin static files,

# relative to this directory. They are copied after the builtin static files,

# so a file named "default.css" will overwrite the builtin "default.css".

# so a file named "default.css" will overwrite the builtin "default.css".



html_static_path = ['sphinx-static']

html_static_path = ['sphinx-static']





html_css_files = [

    'theme_overrides.css',

]



if major <= 1 and minor < 8:

    html_context = {

        'css_files': [

            '_static/theme_overrides.css',

        ],

    }



# Add any extra paths that contain custom files (such as robots.txt or

# Add any extra paths that contain custom files (such as robots.txt or

# .htaccess) here, relative to this directory. These files are copied

# .htaccess) here, relative to this directory. These files are copied

# directly to the root of the documentation.

# directly to the root of the documentation.

Documentation/doc-guide/sphinx.rst

+8 −0
Original line number Original line Diff line number Diff line
@@ -138,6 +138,14 @@ To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make 
variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose

variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose

output.

output.





By default, the build will try to use the Read the Docs sphinx theme:



    https://github.com/readthedocs/sphinx_rtd_theme



If the theme is not available, it will fall-back to the classic one.



The Sphinx theme can be overriden by using the ``DOCS_THEME`` make variable.



To remove the generated documentation, run ``make cleandocs``.

To remove the generated documentation, run ``make cleandocs``.





Writing Documentation

Writing Documentation