On Mon, 24 Oct 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote:
> The conf.py becomes more and more unclear, mainly caused by all those
> out-commented settings. As a result, we have out-dated (rst2pdf) and
> useless (man/texinfo) settings and others (sphinx version) are missed.
> Its time to tidy up:
>
> * drop the out-commented default settings
> * drop no longer used rst2pdf options
> * set minimal Sphinx version (needs_sphinx=1.2)
This change is not cleanup. Cleanups and functional changes must be
separate patches.
Other than that, I could be convinced either way. There's some value in
having the commented out defaults as documentation, and people might get
ideas about what's available and possible. If you do sphinx-quickstart
again and diff the files, you get a better idea what we've changed if
the files are mostly the same. *shrug*.
BR,
Jani.
> * set man_pages empty / since we have man pages not yet
> * set texinfo_documents empty / since we have texinfo not yet
>
> Signed-off-by: Markus Heiser <markus.heiser@xxxxxxxxxxx>
> ---
> Documentation/conf.py | 271 ++++----------------------------------------------
> 1 file changed, 19 insertions(+), 252 deletions(-)
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 02c4081..1c16ba1 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -1,16 +1,10 @@
> # -*- coding: utf-8 -*-
> #
> -# The Linux Kernel documentation build configuration file, created by
> -# sphinx-quickstart on Fri Feb 12 13:51:46 2016.
> -#
> -# This file is execfile()d with the current directory set to its
> -# containing dir.
> +# The Linux Kernel documentation build configuration file. This file is
> +# execfile()d with the current directory set to its containing dir.
> #
> # Note that not all possible configuration values are present in this
> # autogenerated file.
> -#
> -# All configuration values have a default; values that are commented out
> -# serve to show the default.
>
> import sys
> import os
> @@ -19,17 +13,21 @@ import sphinx
> # Get Sphinx version
> major, minor, patch = map(int, sphinx.__version__.split("."))
>
> -
> # If extensions (or modules to document with autodoc) are in another directory,
> # add these directories to sys.path here. If the directory is relative to the
> # documentation root, use os.path.abspath to make it absolute, like shown here.
> sys.path.insert(0, os.path.abspath('sphinx'))
> from load_config import loadConfig
>
> -# -- General configuration ------------------------------------------------
> +# -- General configuration
> +
> +# General information about the project.
> +project = 'The Linux Kernel'
> +copyright = '2016, The kernel development community'
> +author = 'The kernel development community'
>
> # If your documentation needs a minimal Sphinx version, state it here.
> -#needs_sphinx = '1.0'
> +needs_sphinx = '1.2'
>
> # Add any Sphinx extension module names here, as strings. They can be
> # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
> @@ -51,16 +49,11 @@ templates_path = ['_templates']
> source_suffix = '.rst'
>
> # The encoding of source files.
> -#source_encoding = 'utf-8-sig'
> +source_encoding = 'utf-8-sig'
>
> # The master toctree document.
> master_doc = 'index'
>
> -# General information about the project.
> -project = 'The Linux Kernel'
> -copyright = '2016, The kernel development community'
> -author = 'The kernel development community'
> -
> # The version info for the project you're documenting, acts as replacement for
> # |version| and |release|, also used in various other places throughout the
> # built documents.
> @@ -98,47 +91,20 @@ finally:
> # Usually you set "language" from the command line for these cases.
> language = None
>
> -# 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 = ['output']
>
> -# The reST default role (used for this markup: `text`) to use for all
> -# documents.
> -#default_role = None
> -
> -# If true, '()' will be appended to :func: etc. cross-reference text.
> -#add_function_parentheses = True
> -
> -# If true, the current module name will be prepended to all description
> -# unit titles (such as .. function::).
> -#add_module_names = True
> -
> -# If true, sectionauthor and moduleauthor directives will be shown in the
> -# output. They are ignored by default.
> -#show_authors = False
> -
> # 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 = False
>
> primary_domain = 'C'
> highlight_language = 'guess'
>
> -# -- Options for HTML output ----------------------------------------------
> +# -- Options for HTML output
>
> # The theme to use for HTML and HTML Help pages. See the documentation for
> # a list of builtin themes.
> @@ -154,30 +120,6 @@ try:
> 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')
>
> -# 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 for this set of Sphinx documents. If None, it defaults to
> -# "<project> v<release> documentation".
> -#html_title = None
> -
> -# A shorter title for the navigation bar. Default is the same as html_title.
> -#html_short_title = None
> -
> -# The name of an image file (relative to this directory) to place at the top
> -# of the sidebar.
> -#html_logo = None
> -
> -# 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".
> @@ -190,70 +132,13 @@ html_context = {
> ],
> }
>
> -# 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 = True
> -
> -# 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', 'h', 'it', 'ja'
> -# 'nl', 'no', 'pt', 'ro', 'r', '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'
> +html_search_language = 'en'
>
> # Output file base name for HTML help builder.
> htmlhelp_basename = 'TheLinuxKerneldoc'
>
> -# -- Options for LaTeX output ---------------------------------------------
> +# -- Options for LaTeX output
>
> latex_elements = {
> # The paper size ('letterpaper' or 'a4paper').
> @@ -346,65 +231,20 @@ latex_documents = [
> 'The kernel development community', 'manual'),
> ]
>
> -# The name of an image file (relative to this directory) to place at the top of
> -# the title page.
> -#latex_logo = None
> -
> -# For "manual" documents, if this is true, then toplevel headings are parts,
> -# not chapters.
> -#latex_use_parts = False
> -
> -# 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 ---------------------------------------
> +# -- Options for manual page output
>
> # One entry per manual page. List of tuples
> # (source start file, name, description, authors, manual section).
> -man_pages = [
> - (master_doc, 'thelinuxkernel', 'The Linux Kernel Documentation',
> - [author], 1)
> -]
> +man_pages = []
>
> -# If true, show URL addresses after external links.
> -#man_show_urls = False
> -
> -
> -# -- Options for Texinfo output -------------------------------------------
> +# -- Options for Texinfo output
>
> # Grouping the document tree into Texinfo files. List of tuples
> # (source start file, target name, title, author,
> # dir menu entry, description, category)
> -texinfo_documents = [
> - (master_doc, 'TheLinuxKernel', 'The Linux Kernel Documentation',
> - author, 'TheLinuxKernel', 'One line description of project.',
> - 'Miscellaneous'),
> -]
> -
> -# Documents to append as an appendix to all manuals.
> -#texinfo_appendices = []
> -
> -# If false, no module index is generated.
> -#texinfo_domain_indices = True
> +texinfo_documents = []
>
> -# 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 ----------------------------------------------
> +# -- Options for Epub output
>
> # Bibliographic Dublin Core info.
> epub_title = project
> @@ -412,81 +252,10 @@ 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
> -
> -#=======
> -# rst2pdf
> -#
> -# Grouping the document tree into PDF files. List of tuples
> -# (source start file, target name, title, author, options).
> -#
> -# See the Sphinx chapter of http://ralsina.me/static/manual.pdf
> -#
> -# FIXME: Do not add the index file here; the result will be too big. Adding
> -# multiple PDF files here actually tries to get the cross-referencing right
> -# *between* PDF files.
> -pdf_documents = [
> - ('kernel-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'),
> -]
> +# -- Options for kernel extensions
>
> # kernel-doc extension configuration for running Sphinx directly (e.g. by Read
> # the Docs). In a normal build, these are supplied from the Makefile via command
> @@ -494,8 +263,6 @@ pdf_documents = [
> kerneldoc_bin = '../scripts/kernel-doc'
> kerneldoc_srctree = '..'
>
> -# ------------------------------------------------------------------------------
> # Since loadConfig overwrites settings from the global namespace, it has to be
> # the last statement in the conf.py file
> -# ------------------------------------------------------------------------------
> loadConfig(globals())
--
Jani Nikula, Intel Open Source Technology Center
--
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
