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

docs: allow to pass extra DOCS_CSS themes via make 



Specially when the RTD theme is not used, it makes sense to
allow specifying extra CSS files via a make variable.

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


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

Documentation/Makefile

+7 −1
Original line number Diff line number Diff line
@@ -20,6 +20,7 @@ SPHINXBUILD = sphinx-build 
SPHINXOPTS    =

SPHINXDIRS    = .

DOCS_THEME    =

DOCS_CSS      =

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

SPHINX_CONF   = conf.py

PAPER         =
@@ -85,7 +86,10 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) 
	-D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \

	$(ALLSPHINXOPTS) \

	$(abspath $(srctree)/$(src)/$5) \

	$(abspath $(BUILDDIR)/$3/$4)

	$(abspath $(BUILDDIR)/$3/$4) && \

	if [ "x$(DOCS_CSS)" != "x" ]; then \

		cp $(DOCS_CSS) $(BUILDDIR)/$3/_static/; \

	fi



htmldocs:

	@$(srctree)/scripts/sphinx-pre-install --version-check
@@ -157,4 +161,6 @@ dochelp: 
	@echo

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

	@echo

	@echo '   make DOCS_CSS={a .css file} adds a DOCS_CSS override file for html/epub output.'

	@echo

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

Documentation/conf.py

+7 −0
Original line number Diff line number Diff line
@@ -210,6 +210,7 @@ highlight_language = 'none' 


# Default theme

html_theme = 'sphinx_rtd_theme'

html_css_files = []



if "DOCS_THEME" in os.environ:

    html_theme = os.environ["DOCS_THEME"]
@@ -229,6 +230,12 @@ if html_theme == 'sphinx_rtd_theme': 
    except ImportError:

        html_theme = 'classic'



if "DOCS_CSS" in os.environ:

    css = os.environ["DOCS_CSS"].split(" ")



    for l in css:

        html_css_files.append(l)



if major <= 1 and minor < 8:

    html_context = {

        'css_files': [],

Documentation/doc-guide/sphinx.rst

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

output.



It is also possible to pass an extra DOCS_CSS overlay file, in order to customize

the html layout, by using the ``DOCS_CSS`` make variable.



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



    https://github.com/readthedocs/sphinx_rtd_theme