* [PATCH 1/3] doc-rst: generic way to build only sphinx sub-folders
2016-08-08 13:14 [PATCH 0/3] doc-rst: more generic way to build only sphinx sub-folders Markus Heiser
@ 2016-08-08 13:14 ` Markus Heiser
2016-08-12 21:20 ` Jonathan Corbet
2016-08-08 13:14 ` [PATCH 2/3] doc-rst: add stand-alone conf.py to media folder Markus Heiser
` (2 subsequent siblings)
3 siblings, 1 reply; 9+ messages in thread
From: Markus Heiser @ 2016-08-08 13:14 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Markus Heiser, Linux Media Mailing List, linux-doc,
Jonathan Corbet, Mauro Carvalho Chehab
From: Markus Heiser <markus.heiser@darmarIT.de>
Remove the 'DOC_NITPIC_TARGETS' from main $(srctree)/Makefile and add a
more generic way to build only a reST sub-folder.
* control *sub-folders* by environment SPHINXDIRS
* control *build-theme* by environment SPHINX_CONF
Folders with a conf.py file, matching $(srctree)/Documentation/*/conf.py
can be build and distributed *stand-alone*. E.g. to compile only the
html of 'media' and 'gpu' folder use::
make SPHINXDIRS="media gpu" htmldocs
To use an additional sphinx-build configuration (*build-theme*) set the
name of the configuration file to SPHINX_CONF. E.g. to compile only the
html of 'media' with the *nit-picking* build use::
make SPHINXDIRS=media SPHINX_CONF=conf_nitpick.py htmldocs
With this, the Documentation/conf.py is read first and updated with the
configuration values from the Documentation/media/conf_nitpick.py.
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
---
Documentation/DocBook/Makefile | 2 +-
Documentation/Makefile.sphinx | 52 +++++++++++++++++++++++++++----------
Documentation/sphinx/load_config.py | 20 +++++++++-----
Makefile | 6 -----
4 files changed, 53 insertions(+), 27 deletions(-)
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index c481df3..24fd36d 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -6,7 +6,7 @@
# To add a new book the only step required is to add the book to the
# list of DOCBOOKS.
-ifeq ($(IGNORE_DOCBOOKS),)
+ifeq ($(IGNORE_DOCBOOKS)$(SPHINXDIRS),)
DOCBOOKS := z8530book.xml device-drivers.xml \
kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
index bbd7cd4..1549237 100644
--- a/Documentation/Makefile.sphinx
+++ b/Documentation/Makefile.sphinx
@@ -5,9 +5,13 @@
# You can set these variables from the command line.
SPHINXBUILD = sphinx-build
SPHINXOPTS =
+SPHINXDIRS = .
+_SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(srctree)/Documentation/*/conf.py))
+SPHINX_CONF = conf.py
PAPER =
BUILDDIR = $(obj)/output
+
# User-friendly check for sphinx-build
HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)
@@ -33,35 +37,50 @@ PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
KERNELDOC = $(srctree)/scripts/kernel-doc
KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
-ALLSPHINXOPTS = -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) -d $(BUILDDIR)/.doctrees $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) -c $(srctree)/$(src) $(SPHINXOPTS)
+ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-quiet_cmd_sphinx = SPHINX $@
- cmd_sphinx = BUILDDIR=$(BUILDDIR) $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(srctree)/$(src)$3 $(BUILDDIR)/$2
-
-# Build only the media docs, in nitpick mode
-mediadocs:
- $(MAKE) BUILDDIR=$(BUILDDIR) SPHINX_CONF=media/conf_nitpick.py -f $(srctree)/Documentation/media/Makefile htmldocs
- $(call cmd,sphinx,html,/media)
+# commands; the 'cmd' from scripts/Kbuild.include is not *loopable*
+loop_cmd = $(echo-cmd) $(cmd_$(1))
+
+# $2 sphinx builder e.g. "html"
+# $3 name of the build subfolder / e.g. "media", used as:
+# * dest folder relative to $(BUILDDIR) and
+# * cache folder relative to $(BUILDDIR)/.doctrees
+# $4 dest subfolder e.g. "man" for man pages at media/man
+# $5 reST source folder relative to $(srctree)/$(src),
+# e.g. "media" for the linux-tv book-set at ./Documentation/media
+
+quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4);
+ cmd_sphinx = BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
+ $(SPHINXBUILD) \
+ -b $2 \
+ -c $(abspath $(srctree)/$(src)) \
+ -d $(abspath $(BUILDDIR)/.doctrees/$3) \
+ -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \
+ $(ALLSPHINXOPTS) \
+ $(abspath $(srctree)/$(src)/$5) \
+ $(abspath $(BUILDDIR)/$3/$4);
htmldocs:
- $(MAKE) BUILDDIR=$(BUILDDIR) -f $(srctree)/Documentation/media/Makefile $@
- $(call cmd,sphinx,html)
+ $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) -f $(srctree)/Documentation/media/Makefile $@
+ @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
+
pdfdocs:
ifeq ($(HAVE_RST2PDF),0)
$(warning The Python 'rst2pdf' module was not found. Make sure you have the module installed to produce PDF output.)
@echo " SKIP Sphinx $@ target."
else # HAVE_RST2PDF
- $(call cmd,sphinx,pdf)
+ @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,pdf,$(var),pdf,$(var)))
endif # HAVE_RST2PDF
epubdocs:
- $(call cmd,sphinx,epub)
+ @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
xmldocs:
- $(call cmd,sphinx,xml)
+ @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))
# no-ops for the Sphinx toolchain
sgmldocs:
@@ -75,10 +94,15 @@ cleandocs:
dochelp:
@echo ' Linux kernel internal documentation in different formats (Sphinx):'
@echo ' htmldocs - HTML'
- @echo ' mediadocs - built only media books in HTML on nitpick mode'
@echo ' pdfdocs - PDF'
@echo ' epubdocs - EPUB'
@echo ' xmldocs - XML'
@echo ' cleandocs - clean all generated files'
+ @echo
+ @echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
+ @echo ' valid values for SPHINXDIRS are: $(_SPHINXDIRS)'
+ @echo
+ @echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'
+ @echo ' configuration. This is e.g. useful to build with nit-picking config.'
endif # HAVE_SPHINX
diff --git a/Documentation/sphinx/load_config.py b/Documentation/sphinx/load_config.py
index 44bdd22..88e5e4a 100644
--- a/Documentation/sphinx/load_config.py
+++ b/Documentation/sphinx/load_config.py
@@ -2,6 +2,7 @@
# pylint: disable=R0903, C0330, R0914, R0912, E0401
import os
+import sys
from sphinx.util.pycompat import execfile_
# ------------------------------------------------------------------------------
@@ -16,10 +17,17 @@ def loadConfig(namespace):
maintain *build themes*. """
config_file = os.environ.get("SPHINX_CONF", None)
- if config_file is not None and os.path.exists(config_file):
+ if (config_file is not None
+ and os.path.normpath(namespace["__file__"]) != os.path.normpath(config_file) ):
config_file = os.path.abspath(config_file)
- config = namespace.copy()
- config['__file__'] = config_file
- execfile_(config_file, config)
- del config['__file__']
- namespace.update(config)
+
+ if os.path.isfile(config_file):
+ sys.stdout.write("load additional sphinx-config: %s\n" % config_file)
+ config = namespace.copy()
+ config['__file__'] = config_file
+ execfile_(config_file, config)
+ del config['__file__']
+ namespace.update(config)
+ else:
+ sys.stderr.write("WARNING: additional sphinx-config not found: %s\n" % config_file)
+
diff --git a/Makefile b/Makefile
index 08ef6c1..3560355 100644
--- a/Makefile
+++ b/Makefile
@@ -1439,12 +1439,6 @@ $(DOC_TARGETS): scripts_basic FORCE
$(Q)$(MAKE) $(build)=Documentation -f $(srctree)/Documentation/Makefile.sphinx $@
$(Q)$(MAKE) $(build)=Documentation/DocBook $@
-DOC_NITPIC_TARGETS := mediadocs
-PHONY += $(DOC_NITPIC_TARGETS)
-$(DOC_NITPIC_TARGETS): scripts_basic FORCE
- $(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype
- $(Q)$(MAKE) $(build)=Documentation -f $(srctree)/Documentation/Makefile.sphinx $@
-
else # KBUILD_EXTMOD
###
--
2.7.4
^ permalink raw reply related [flat|nested] 9+ messages in thread* [PATCH 2/3] doc-rst: add stand-alone conf.py to media folder
2016-08-08 13:14 [PATCH 0/3] doc-rst: more generic way to build only sphinx sub-folders Markus Heiser
2016-08-08 13:14 ` [PATCH 1/3] doc-rst: " Markus Heiser
@ 2016-08-08 13:14 ` Markus Heiser
2016-08-08 13:15 ` [PATCH 3/3] doc-rst: add stand-alone conf.py to gpu folder Markus Heiser
2016-08-09 15:21 ` [PATCH 0/3] doc-rst: more generic way to build only sphinx sub-folders Jonathan Corbet
3 siblings, 0 replies; 9+ messages in thread
From: Markus Heiser @ 2016-08-08 13:14 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Markus Heiser, Linux Media Mailing List, linux-doc,
Jonathan Corbet, Mauro Carvalho Chehab
From: Markus Heiser <markus.heiser@darmarIT.de>
With the media/conf.py, the media folder can be build and distributed
stand-alone. BTW fixed python indentation in media/conf_nitpick.py.
Python indentation is 4 spaces [1] and Python 3 disallows mixing the use
of tabs and spaces for indentation.
[1] https://www.python.org/dev/peps/pep-0008/#indentation
[2] https://www.python.org/dev/peps/pep-0008/#tabs-or-spaces
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
---
Documentation/media/conf.py | 3 +
Documentation/media/conf_nitpick.py | 150 +++++++++++++++++++-----------------
2 files changed, 81 insertions(+), 72 deletions(-)
create mode 100644 Documentation/media/conf.py
diff --git a/Documentation/media/conf.py b/Documentation/media/conf.py
new file mode 100644
index 0000000..62bdba2
--- /dev/null
+++ b/Documentation/media/conf.py
@@ -0,0 +1,3 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = 'Linux Media Subsystem Documentation'
diff --git a/Documentation/media/conf_nitpick.py b/Documentation/media/conf_nitpick.py
index 9034d7f..e794e3d 100644
--- a/Documentation/media/conf_nitpick.py
+++ b/Documentation/media/conf_nitpick.py
@@ -1,4 +1,10 @@
-nitpicky=True
+# -*- coding: utf-8; mode: python -*-
+
+project = 'Linux Media Subsystem Documentation'
+# within nit-picking build, do not refer to any intersphinx object
+intersphinx_mapping = {}
+
+nitpicky = True
# It is possible to run Sphinx in nickpick mode with:
# make SPHINXOPTS=-n htmldocs
@@ -10,76 +16,76 @@ nitpicky=True
# The list below has a list of such symbols to be ignored in nitpick mode
#
nitpick_ignore = [
- ("c:func", "clock_gettime"),
- ("c:func", "close"),
- ("c:func", "container_of"),
- ("c:func", "determine_valid_ioctls"),
- ("c:func", "ERR_PTR"),
- ("c:func", "ioctl"),
- ("c:func", "IS_ERR"),
- ("c:func", "mmap"),
- ("c:func", "open"),
- ("c:func", "pci_name"),
- ("c:func", "poll"),
- ("c:func", "PTR_ERR"),
- ("c:func", "read"),
- ("c:func", "release"),
- ("c:func", "set"),
- ("c:func", "struct fd_set"),
- ("c:func", "struct pollfd"),
- ("c:func", "usb_make_path"),
- ("c:func", "write"),
- ("c:type", "atomic_t"),
- ("c:type", "bool"),
- ("c:type", "buf_queue"),
- ("c:type", "device"),
- ("c:type", "device_driver"),
- ("c:type", "device_node"),
- ("c:type", "enum"),
- ("c:type", "file"),
- ("c:type", "i2c_adapter"),
- ("c:type", "i2c_board_info"),
- ("c:type", "i2c_client"),
- ("c:type", "ktime_t"),
- ("c:type", "led_classdev_flash"),
- ("c:type", "list_head"),
- ("c:type", "lock_class_key"),
- ("c:type", "module"),
- ("c:type", "mutex"),
- ("c:type", "pci_dev"),
- ("c:type", "pdvbdev"),
- ("c:type", "poll_table_struct"),
- ("c:type", "s32"),
- ("c:type", "s64"),
- ("c:type", "sd"),
- ("c:type", "spi_board_info"),
- ("c:type", "spi_device"),
- ("c:type", "spi_master"),
- ("c:type", "struct fb_fix_screeninfo"),
- ("c:type", "struct pollfd"),
- ("c:type", "struct timeval"),
- ("c:type", "struct video_capability"),
- ("c:type", "u16"),
- ("c:type", "u32"),
- ("c:type", "u64"),
- ("c:type", "u8"),
- ("c:type", "union"),
- ("c:type", "usb_device"),
+ ("c:func", "clock_gettime"),
+ ("c:func", "close"),
+ ("c:func", "container_of"),
+ ("c:func", "determine_valid_ioctls"),
+ ("c:func", "ERR_PTR"),
+ ("c:func", "ioctl"),
+ ("c:func", "IS_ERR"),
+ ("c:func", "mmap"),
+ ("c:func", "open"),
+ ("c:func", "pci_name"),
+ ("c:func", "poll"),
+ ("c:func", "PTR_ERR"),
+ ("c:func", "read"),
+ ("c:func", "release"),
+ ("c:func", "set"),
+ ("c:func", "struct fd_set"),
+ ("c:func", "struct pollfd"),
+ ("c:func", "usb_make_path"),
+ ("c:func", "write"),
+ ("c:type", "atomic_t"),
+ ("c:type", "bool"),
+ ("c:type", "buf_queue"),
+ ("c:type", "device"),
+ ("c:type", "device_driver"),
+ ("c:type", "device_node"),
+ ("c:type", "enum"),
+ ("c:type", "file"),
+ ("c:type", "i2c_adapter"),
+ ("c:type", "i2c_board_info"),
+ ("c:type", "i2c_client"),
+ ("c:type", "ktime_t"),
+ ("c:type", "led_classdev_flash"),
+ ("c:type", "list_head"),
+ ("c:type", "lock_class_key"),
+ ("c:type", "module"),
+ ("c:type", "mutex"),
+ ("c:type", "pci_dev"),
+ ("c:type", "pdvbdev"),
+ ("c:type", "poll_table_struct"),
+ ("c:type", "s32"),
+ ("c:type", "s64"),
+ ("c:type", "sd"),
+ ("c:type", "spi_board_info"),
+ ("c:type", "spi_device"),
+ ("c:type", "spi_master"),
+ ("c:type", "struct fb_fix_screeninfo"),
+ ("c:type", "struct pollfd"),
+ ("c:type", "struct timeval"),
+ ("c:type", "struct video_capability"),
+ ("c:type", "u16"),
+ ("c:type", "u32"),
+ ("c:type", "u64"),
+ ("c:type", "u8"),
+ ("c:type", "union"),
+ ("c:type", "usb_device"),
- ("cpp:type", "boolean"),
- ("cpp:type", "fd"),
- ("cpp:type", "fd_set"),
- ("cpp:type", "int16_t"),
- ("cpp:type", "NULL"),
- ("cpp:type", "off_t"),
- ("cpp:type", "pollfd"),
- ("cpp:type", "size_t"),
- ("cpp:type", "ssize_t"),
- ("cpp:type", "timeval"),
- ("cpp:type", "__u16"),
- ("cpp:type", "__u32"),
- ("cpp:type", "__u64"),
- ("cpp:type", "uint16_t"),
- ("cpp:type", "uint32_t"),
- ("cpp:type", "video_system_t"),
+ ("cpp:type", "boolean"),
+ ("cpp:type", "fd"),
+ ("cpp:type", "fd_set"),
+ ("cpp:type", "int16_t"),
+ ("cpp:type", "NULL"),
+ ("cpp:type", "off_t"),
+ ("cpp:type", "pollfd"),
+ ("cpp:type", "size_t"),
+ ("cpp:type", "ssize_t"),
+ ("cpp:type", "timeval"),
+ ("cpp:type", "__u16"),
+ ("cpp:type", "__u32"),
+ ("cpp:type", "__u64"),
+ ("cpp:type", "uint16_t"),
+ ("cpp:type", "uint32_t"),
+ ("cpp:type", "video_system_t"),
]
--
2.7.4
^ permalink raw reply related [flat|nested] 9+ messages in thread