From: "Heiser, Markus" <markus.heiser@xxxxxxxxxxx>
Documentation/Makefile.reST and Documentation/conf.py
Makefile and basic 'sphinx config' file to build the various reST
documents and output formats. Provides the basic sphinx-doc build
infrastructure including the *sphinx-subprojects* feature. With this
feature each book can be build and distributed stand-alone.
Documentation/sphinx-static and Documentation/sphinx-tex
Paths that contain sphinx-doc custom static files (such as style
sheets).
Documentation/books
In this folder, the books with reST markup are placed. To
provide *sphinx-subprojects*, each book has its one folder and
a (optional) Documentation/books/{book-name}.conf file
which *overwrites* the basic configuration from Documentation/conf.py
The concept of the infrastructure was taken from the sphkerneldoc
project [1]
[1] http://return42.github.io/sphkerneldoc
Signed-off-by: Markus Heiser <markus.heiser@xxxxxxxxxxx>
---
Documentation/.gitignore | 2 +
Documentation/Makefile.reST | 111 ++++++++
Documentation/books/.gitignore | 0
Documentation/conf.py | 357 ++++++++++++++++++++++++
Documentation/sphinx-static/theme_overrides.css | 45 +++
Documentation/sphinx-tex/Makefile | 88 ++++++
6 files changed, 603 insertions(+)
create mode 100644 Documentation/.gitignore
create mode 100644 Documentation/Makefile.reST
create mode 100644 Documentation/books/.gitignore
create mode 100644 Documentation/conf.py
create mode 100644 Documentation/sphinx-static/theme_overrides.css
create mode 100644 Documentation/sphinx-tex/Makefile
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
new file mode 100644
index 0000000..1886a596
--- /dev/null
+++ b/Documentation/.gitignore
@@ -0,0 +1,2 @@
+cache/
+dist/
\ No newline at end of file
diff --git a/Documentation/Makefile.reST b/Documentation/Makefile.reST
new file mode 100644
index 0000000..67bdcd0
--- /dev/null
+++ b/Documentation/Makefile.reST
@@ -0,0 +1,111 @@
+# -*- coding: utf-8; mode: make -*-
+# Makefile for restructuredText (reST) content
+
+export PYTHONPATH := $(abspath ../scripts/site-python/):$(PYTHONPATH)
+
+ifndef obj
+ obj := .
+endif
+
+CACHE := $(obj)/cache
+BOOKS_FOLDER := books
+DIST := $(obj)/dist
+
+# External programs used
+
+SPHINXBUILD := sphinx-build
+PDFLATEX := pdflatex
+
+BOOKS := $(filter %/, $(wildcard $(BOOKS_FOLDER)/*/))
+BOOKS := $(BOOKS:%/=%)
+BOOKS_HTML := $(patsubst %, %.html, $(BOOKS))
+BOOKS_HTML_CLEAN := $(patsubst %, %.clean, $(BOOKS))
+
+# sphinx-doc setup
+SPHINXOPTS :=
+PAPER :=
+
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+FMT = cat
+ifeq ($(shell which fmt >/dev/null 2>&1; echo $$?), 0)
+FMT = fmt
+endif
+
+# ------------------------------------------------------------------------------
+# requirements
+# ------------------------------------------------------------------------------
+
+.PHONY: sphinx-doc
+
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+sphinx-doc: msg-SphinxDoc
+ $(error The '$(SPHINXBUILD)' command was not found)
+else
+sphinx-doc:
+ @:
+endif
+
+msg-SphinxDoc:
+ @echo "\nsphinx-doc:\n\n\
+ Make sure you have an updated Sphinx installed, grab it from\
+ http://sphinx-doc.org or install it from the python package\
+ manager (pip). \n\n\
+ On debian based OS these requirements are installed by::\n\n\
+ sudo apt-get install pip \n\n\
+ pip install Sphinx\n" | $(FMT)
+
+# ------------------------------------------------------------------------------
+# usage
+# ------------------------------------------------------------------------------
+
+.PHONY: help help-requirements
+help:
+ @echo "Please use \`make <target>' where <target> is one of ..."
+ @echo
+ @echo "all-HTML : builds all HTML outputs/targets"
+ @echo
+ @echo "make {book/*} : builds only the HTML of {book}, valid"
+ @echo " values for {book/*} are: \n\n $(BOOKS_HTML)" | $(FMT)
+ @echo
+ @echo "The output formats are placed into folder:"
+ @echo
+ @echo " $(DIST)"
+ @echo
+
+help-requirements: msg-SphinxDoc
+
+
+# ------------------------------------------------------------------------------
+# main targets
+# ------------------------------------------------------------------------------
+
+.PHONY: all-HTML clean-HTML $(BOOKS_HTML)
+
+all-HTML: sphinx-doc $(BOOKS_HTML)
+clean-HTML: clean-books.html
+
+$(DIST):
+ mkdir -p $(DIST)
+
+# ------------------------------------------------------------------------------
+# BOOKs
+# ------------------------------------------------------------------------------
+
+# reST-book --> HTML (sphinx-doc projects)
+# ----------------------------------------
+
+$(BOOKS_HTML): sphinx-doc | $(DIST)
+ @echo "building $@ ..."
+ SPHPROJ_CONF=$(patsubst %.html,%.conf,$@) $(SPHINXBUILD) -c . -b html -d $(CACHE)/doctrees/$(patsubst %.html,%,$@) $(patsubst %.html,%,$@) $(DIST)/$(patsubst %.html,%,$@)
+
+$(BOOKS_HTML_CLEAN):
+ rm -rf $(DIST)/$(patsubst %.clean,%,$@) $(CACHE)/doctrees/$(patsubst %.clean,%,$@)
+
+.PHONY: clean-books.html
+clean-books.html: $(BOOKS_HTML_CLEAN)
+
diff --git a/Documentation/books/.gitignore b/Documentation/books/.gitignore
new file mode 100644
index 0000000..e69de29
diff --git a/Documentation/conf.py b/Documentation/conf.py
new file mode 100644
index 0000000..50a7a67
--- /dev/null
+++ b/Documentation/conf.py
@@ -0,0 +1,357 @@
+# -*- coding: utf-8 -*-
+#
+# This is the common sphinx-build configuration used by the kernel documentation
+# book's build process. About config values consult:
+#
+# * http://www.sphinx-doc.org/en/stable/config.html
+#
+# Project (book) specific configuration is read from a file given by the
+# SPHPROJ_CONF environment (see function loadPrjConfig).
+
+import sys
+import os
+from os.path import join as pathjoin
+from os.path import abspath, dirname, splitext, basename, exists
+
+BASE_FOLDER = abspath(pathjoin(dirname(__file__)))
+
+# ------------------------------------------------------------------------------
+def loadPrjConfig():
+# ------------------------------------------------------------------------------
+
+ from sphinx.util.pycompat import execfile_
+ from sphinx.util.osutil import cd
+
+ config_file = os.environ.get("SPHPROJ_CONF", None)
+ if config_file is not None and exists(config_file):
+ config_file = abspath(config_file)
+ main_name = splitext(basename(config_file))[0]
+ config = globals().copy()
+ config.update({
+ "main_name" : main_name
+ })
+ config['__file__'] = config_file
+ execfile_(config_file, config)
+ globals().update(config)
+
+# ------------------------------------------------------------------------------
+# extensions
+# ------------------------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here or add it to the PYTHONPATH
+
+# ------------------------------------------------------------------------------
+# General configuration
+# ------------------------------------------------------------------------------
+
+# The default language to highlight source code in.
+highlight_language = "none"
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# external links
+# --------------
+#
+# usage: lorem :man:`dvbv5-scan` ipsum
+
+extlinks = {
+ 'man' : ('http://manpages.ubuntu.com/cgi-bin/search.py?q=%s', ' ')
+ , 'deb' : ('http://packages.ubuntu.com/xenial/%s', ' ')
+ }
+
+# Intersphinx
+# -----------
+#
+# usage: lorem :ref:`dtv_get_frontend <linux:dtv_get_frontend>` ipsum
+
+intersphinx_mapping = {}
+intersphinx_mapping['linux'] = ('https://return42.github.io/sphkerneldoc/linux_src_doc/', None)
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+ "linuxdoc.rstFlatTable"
+ , "linuxdoc.rstKernelDoc"
+ , 'sphinx.ext.autodoc'
+ , 'sphinx.ext.extlinks'
+ #, 'sphinx.ext.autosummary'
+ #, 'sphinx.ext.doctest'
+ , 'sphinx.ext.todo'
+ , 'sphinx.ext.coverage'
+ #, 'sphinx.ext.pngmath'
+ #, 'sphinx.ext.mathjax'
+ , 'sphinx.ext.viewcode'
+ , 'sphinx.ext.intersphinx'
+ , 'sphinx.ext.ifconfig'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['sphinx-templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The encoding of source files.
+source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['sphinx-tex', 'sphinx-static', 'sphinx-templates']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+keep_warnings = False
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+# If true, fatal errors (like missing function descripions) raise an
+# error. Default: True
+kernel_doc_raise_error = False
+
+# ------------------------------------------------------------------------------
+# Options for HTML output
+# ------------------------------------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'sphinx_rtd_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
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = pathjoin(BASE_FOLDER, "logo.gif")
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# 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_static_path = ['sphinx-static']
+
+html_context = {
+ 'css_files': [
+ '_static/theme_overrides.css',
+ ],
+}
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+html_show_sphinx = False
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Language to be used for generating the HTML full-text search index.
+# Sphinx supports the following languages:
+# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
+# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
+html_search_language = 'en'
+
+# A dictionary with options for the search language support, empty by default.
+# Now only 'ja' uses this config value
+#html_search_options = {'type': 'default'}
+
+# The name of a javascript file (relative to the configuration directory) that
+# implements a search results scorer. If empty, the default will be used.
+#html_search_scorer = 'scorer.js'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Kernel-Doc'
+
+# ------------------------------------------------------------------------------
+# Options for LaTeX output
+# ------------------------------------------------------------------------------
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = pathjoin(BASE_FOLDER, "sphinx-tex", "logo.png")
+
+#latex_additional_files = [
+# pathjoin(BASE_FOLDER, "sphinx-tex", "Makefile")
+#]
+
+# If true, show page references after internal links.
+# latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+# ------------------------------------------------------------------------------
+# Options for manual page output
+# ------------------------------------------------------------------------------
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+# ------------------------------------------------------------------------------
+# Options for Texinfo output
+# ------------------------------------------------------------------------------
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
+
+# ------------------------------------------------------------------------------
+# Options for Epub output
+# ------------------------------------------------------------------------------
+
+# Bibliographic Dublin Core info.
+# epub_title = project
+# epub_author = author
+# epub_publisher = author
+# epub_copyright = copyright
+
+# The basename for the epub file. It defaults to the project name.
+#epub_basename = project
+
+# The HTML theme for the epub output. Since the default themes are not
+# optimized for small screen space, using the same theme for HTML and epub
+# output is usually not wise. This defaults to 'epub', a theme designed to save
+# visual space.
+#epub_theme = 'epub'
+
+# The language of the text. It defaults to the language option
+# or 'en' if the language is not set.
+#epub_language = ''
+
+# The scheme of the identifier. Typical schemes are ISBN or URL.
+#epub_scheme = ''
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#epub_identifier = ''
+
+# A unique identification for the text.
+#epub_uid = ''
+
+# A tuple containing the cover image and cover page html template filenames.
+#epub_cover = ()
+
+# A sequence of (type, uri, title) tuples for the guide element of content.opf.
+#epub_guide = ()
+
+# HTML files that should be inserted before the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_pre_files = []
+
+# HTML files that should be inserted after the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_post_files = []
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+# The depth of the table of contents in toc.ncx.
+#epub_tocdepth = 3
+
+# Allow duplicate toc entries.
+#epub_tocdup = True
+
+# Choose between 'default' and 'includehidden'.
+#epub_tocscope = 'default'
+
+# Fix unsupported image types using the Pillow.
+#epub_fix_images = False
+
+# Scale large images.
+#epub_max_image_width = 0
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#epub_show_urls = 'inline'
+
+# If false, no index is generated.
+#epub_use_index = True
+
+# ------------------------------------------------------------------------------
+loadPrjConfig()
+# ------------------------------------------------------------------------------
diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css
new file mode 100644
index 0000000..cd1277c
--- /dev/null
+++ b/Documentation/sphinx-static/theme_overrides.css
@@ -0,0 +1,45 @@
+/* -*- coding: utf-8; mode: css -*-
+ *
+ * This is a customization of the "Read The Doc" (RTD) theme.
+ *
+ */
+
+@media screen {
+
+ /* inline literal: drop the borderbox and red color */
+
+ code,.rst-content tt,.rst-content code {
+ color: inherit;
+ border: none;
+ background: inherit;
+ font-size: 85%;
+ }
+
+ .rst-content tt.literal,.rst-content tt.literal,.rst-content code.literal {
+ color: inherit;
+ }
+
+ /* captions:
+ *
+ * - captions should have 100% (not 85%) font size
+ * - hide the permalink symbol as long as link is not hovered
+ */
+
+ caption, .wy-table caption, .rst-content table.field-list caption {
+ font-size: 100%;
+ }
+
+ caption a.headerlink { opacity: 0; }
+ caption a.headerlink:hover { opacity: 1; }
+
+ /* table:
+ *
+ * - Sequences of whitespace should collapse into a single whitespace.
+ * - make the overflow auto (scrollbar if needed)
+ * - align caption "left" ("center" is unsuitable on vast tables)
+ */
+
+ .wy-table-responsive table td { white-space: normal; }
+ .wy-table-responsive { overflow: auto; }
+ .rst-content table.docutils caption { text-align: left; font-size: 100%; }
+}
diff --git a/Documentation/sphinx-tex/Makefile b/Documentation/sphinx-tex/Makefile
new file mode 100644
index 0000000..d2f7621
--- /dev/null
+++ b/Documentation/sphinx-tex/Makefile
@@ -0,0 +1,88 @@
+# Makefile for Sphinx LaTeX output
+
+ALLDOCS = $(basename $(wildcard *.tex))
+ALLPDF = $(addsuffix .pdf,$(ALLDOCS))
+ALLDVI = $(addsuffix .dvi,$(ALLDOCS))
+
+# Prefix for archive names
+ARCHIVEPRREFIX =
+
+# Additional LaTeX options
+LATEXOPTS = # -interaction=batchmode
+LATEX_ENV = max_print_line=120
+
+# format: pdf or dvi
+FMT = pdf
+
+LATEX = $(LATEX_ENV) latex
+PDFLATEX = $(LATEX_ENV) FIXME_xelatex
+MAKEINDEX = $(LATEX_ENV) makeindex
+
+all: $(ALLPDF)
+
+all-pdf: $(ALLPDF)
+
+dist-pdf:
+ mkdir -p $(DIST_BOOKS)
+ cp $(ALLPDF) $(DIST_BOOKS)
+
+all-dvi: $(ALLDVI)
+
+all-ps: all-dvi
+ for f in *.dvi; do dvips $$f; done
+
+all-pdf-ja:
+ for f in *.pdf *.png *.gif *.jpg *.jpeg; do extractbb $$f; done
+ for f in *.tex; do platex -kanji=utf8 $(LATEXOPTS) $$f; done
+ for f in *.tex; do platex -kanji=utf8 $(LATEXOPTS) $$f; done
+ for f in *.tex; do platex -kanji=utf8 $(LATEXOPTS) $$f; done
+ -for f in *.idx; do mendex -U -f -d "`basename $$f .idx`.dic" -s python.ist $$f; done
+ for f in *.tex; do platex -kanji=utf8 $(LATEXOPTS) $$f; done
+ for f in *.tex; do platex -kanji=utf8 $(LATEXOPTS) $$f; done
+ for f in *.dvi; do dvipdfmx $$f; done
+
+zip: all-$(FMT)
+ mkdir $(ARCHIVEPREFIX)docs-$(FMT)
+ cp $(ALLPDF) $(ARCHIVEPREFIX)docs-$(FMT)
+ zip -q -r -9 $(ARCHIVEPREFIX)docs-$(FMT).zip $(ARCHIVEPREFIX)docs-$(FMT)
+ rm -r $(ARCHIVEPREFIX)docs-$(FMT)
+
+tar: all-$(FMT)
+ mkdir $(ARCHIVEPREFIX)docs-$(FMT)
+ cp $(ALLPDF) $(ARCHIVEPREFIX)docs-$(FMT)
+ tar cf $(ARCHIVEPREFIX)docs-$(FMT).tar $(ARCHIVEPREFIX)docs-$(FMT)
+ rm -r $(ARCHIVEPREFIX)docs-$(FMT)
+
+gz: tar
+ gzip -9 < $(ARCHIVEPREFIX)docs-$(FMT).tar > $(ARCHIVEPREFIX)docs-$(FMT).tar.gz
+
+bz2: tar
+ bzip2 -9 -k $(ARCHIVEPREFIX)docs-$(FMT).tar
+
+xz: tar
+ xz -9 -k $(ARCHIVEPREFIX)docs-$(FMT).tar
+
+# The number of LaTeX runs is quite conservative, but I don't expect it
+# to get run often, so the little extra time won't hurt.
+%.dvi: %.tex
+ $(LATEX) $(LATEXOPTS) '$<'
+ $(LATEX) $(LATEXOPTS) '$<'
+ $(LATEX) $(LATEXOPTS) '$<'
+ -$(MAKEINDEX) -s python.ist '$(basename $<).idx'
+ $(LATEX) $(LATEXOPTS) '$<'
+ $(LATEX) $(LATEXOPTS) '$<'
+
+%.pdf: %.tex
+ $(PDFLATEX) $(LATEXOPTS) '$<'
+ $(PDFLATEX) $(LATEXOPTS) '$<'
+ $(PDFLATEX) $(LATEXOPTS) '$<'
+ -$(MAKEINDEX) -s python.ist '$(basename $<).idx'
+ $(PDFLATEX) $(LATEXOPTS) '$<'
+ $(PDFLATEX) $(LATEXOPTS) '$<'
+
+clean:
+ rm -f *.log *.ind *.aux *.toc *.syn *.idx *.out *.ilg *.pla *.ps *.tar *.tar.gz *.tar.bz2 *.tar.xz $(ALLPDF) $(ALLDVI)
+
+.PHONY: all all-pdf all-dvi all-ps clean zip tar gz bz2 xz
+.PHONY: all-pdf-ja
+
--
v4.7-rc-2
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
