From 22cba31bae9dc357622f09d22b82ca5a112b4fde Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 19 May 2016 15:14:05 +0300 Subject: Documentation/sphinx: add basic working Sphinx configuration and build Add basic configuration and makefile to build documentation from any .rst files under Documentation using Sphinx. For starters, there's just the placeholder index.rst. At the top level Makefile, hook Sphinx documentation targets alongside (but independent of) the DocBook toolchain, having both be run on the various 'make *docs' targets. All Sphinx processing is placed into Documentation/Makefile.sphinx. Both that and the Documentation/DocBook/Makefile are now expected to handle all the documentation targets, explicitly ignoring them if they're not relevant for that particular toolchain. The changes to the existing DocBook Makefile are kept minimal. There is graceful handling of missing Sphinx and rst2pdf (which is needed for pdf output) by checking for the tool and python module, respectively, with informative messages to the user. If the Read the Docs theme (sphinx_rtd_theme) is available, use it, but otherwise gracefully fall back to the Sphinx default theme, with an informative message to the user, and slightly less pretty HTML output. Sphinx can now handle htmldocs, pdfdocs (if rst2pdf is available), epubdocs and xmldocs targets. The output documents are written into per output type subdirectories under Documentation/output. Finally, you can pass options to sphinx-build using the SPHINXBUILD make variable. For example, 'make SPHINXOPTS=-v htmldocs' for more verbose output from Sphinx. This is based on the original work by Jonathan Corbet, but he probably wouldn't recognize this as his own anymore. Signed-off-by: Jani Nikula --- Makefile | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'Makefile') diff --git a/Makefile b/Makefile index 0f70de63cfdb..8908a51b895a 100644 --- a/Makefile +++ b/Makefile @@ -1412,8 +1412,11 @@ $(help-board-dirs): help-%: # Documentation targets # --------------------------------------------------------------------------- -%docs: scripts_basic FORCE +DOC_TARGETS := xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs +PHONY += $(DOC_TARGETS) +$(DOC_TARGETS): scripts_basic FORCE $(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype + $(Q)$(MAKE) $(build)=Documentation -f $(srctree)/Documentation/Makefile.sphinx $@ $(Q)$(MAKE) $(build)=Documentation/DocBook $@ else # KBUILD_EXTMOD -- cgit v1.2.3-59-g8ed1b From ebc88ef05c825024a5d95285459b8c842c095c0f Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Wed, 22 Jun 2016 15:41:48 +0300 Subject: Documentation: add top level 'make help' output for Sphinx While there's slight overlap with the DocBook help now, this can stay intact when the DocBook help goes away. Signed-off-by: Jani Nikula --- Documentation/DocBook/Makefile | 4 ++-- Documentation/Makefile.sphinx | 8 ++++++++ Makefile | 2 ++ 3 files changed, 12 insertions(+), 2 deletions(-) (limited to 'Makefile') diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index e0c7e1e0590b..496d4295ec38 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -218,7 +218,7 @@ silent_gen_xml = : ### # Help targets as used by the top-level makefile dochelp: - @echo ' Linux kernel internal documentation in different formats:' + @echo ' Linux kernel internal documentation in different formats (DocBook):' @echo ' htmldocs - HTML' @echo ' pdfdocs - PDF' @echo ' psdocs - Postscript' @@ -227,7 +227,7 @@ dochelp: @echo ' installmandocs - install man pages generated by mandocs' @echo ' cleandocs - clean all generated DocBook files' @echo - @echo 'make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml' + @echo ' make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml' @echo ' valid values for DOCBOOKS are: $(DOCBOOKS)' diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index addf32309bc3..810c11f0d37f 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -60,4 +60,12 @@ installmandocs: cleandocs: $(Q)rm -rf $(BUILDDIR) +dochelp: + @echo ' Linux kernel internal documentation in different formats (Sphinx):' + @echo ' htmldocs - HTML' + @echo ' pdfdocs - PDF' + @echo ' epubdocs - EPUB' + @echo ' xmldocs - XML' + @echo ' cleandocs - clean all generated files' + endif # HAVE_SPHINX diff --git a/Makefile b/Makefile index 8908a51b895a..f7f393c40886 100644 --- a/Makefile +++ b/Makefile @@ -1364,6 +1364,8 @@ help: @$(MAKE) $(build)=$(package-dir) help @echo '' @echo 'Documentation targets:' + @$(MAKE) -f $(srctree)/Documentation/Makefile.sphinx dochelp + @echo '' @$(MAKE) -f $(srctree)/Documentation/DocBook/Makefile dochelp @echo '' @echo 'Architecture specific targets ($(SRCARCH)):' -- cgit v1.2.3-59-g8ed1b From a569bf69f069a86a6914453cc1ab5371d173caf1 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Fri, 1 Jul 2016 15:03:34 +0300 Subject: Documentation: add cleanmediadocs to the documentation targets This was broken when updating the documentation targets for the Sphinx build, and moving from %docs target pattern to explicitly listed targets. Cc: Markus Heiser Cc: Mauro Carvalho Chehab Fixes: 22cba31bae9d ("Documentation/sphinx: add basic working Sphinx configuration and build") Signed-off-by: Jani Nikula Signed-off-by: Jonathan Corbet --- Documentation/Makefile.sphinx | 1 + Makefile | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) (limited to 'Makefile') diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index 810c11f0d37f..6c203745b6c6 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -56,6 +56,7 @@ sgmldocs: psdocs: mandocs: installmandocs: +cleanmediadocs: cleandocs: $(Q)rm -rf $(BUILDDIR) diff --git a/Makefile b/Makefile index f7f393c40886..34bc4e22ec0b 100644 --- a/Makefile +++ b/Makefile @@ -1414,7 +1414,7 @@ $(help-board-dirs): help-%: # Documentation targets # --------------------------------------------------------------------------- -DOC_TARGETS := xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs +DOC_TARGETS := xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs cleanmediadocs PHONY += $(DOC_TARGETS) $(DOC_TARGETS): scripts_basic FORCE $(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype -- cgit v1.2.3-59-g8ed1b