diff options
Diffstat (limited to 'Documentation/conf.py')
| -rw-r--r-- | Documentation/conf.py | 126 |
1 files changed, 76 insertions, 50 deletions
diff --git a/Documentation/conf.py b/Documentation/conf.py index 700516238d3f..574896cca198 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -9,6 +9,8 @@ import os import shutil import sys +from textwrap import dedent + import sphinx # If extensions (or modules to document with autodoc) are in another directory, @@ -42,11 +44,22 @@ exclude_patterns = [] dyn_include_patterns = [] dyn_exclude_patterns = ["output"] -# Properly handle include/exclude patterns -# ---------------------------------------- +# Currently, only netlink/specs has a parser for yaml. +# Prefer using include patterns if available, as it is faster +if has_include_patterns: + dyn_include_patterns.append("netlink/specs/*.yaml") +else: + dyn_exclude_patterns.append("netlink/*.yaml") + dyn_exclude_patterns.append("devicetree/bindings/**.yaml") + dyn_exclude_patterns.append("core-api/kho/bindings/**.yaml") + +# Properly handle directory patterns and LaTeX docs +# ------------------------------------------------- -def update_patterns(app, config): +def config_init(app, config): """ + Initialize path-dependent variabled + On Sphinx, all directories are relative to what it is passed as SOURCEDIR parameter for sphinx-build. Due to that, all patterns that have directory names on it need to be dynamically set, after @@ -77,6 +90,38 @@ def update_patterns(app, config): config.exclude_patterns.append(rel_path) + # LaTeX and PDF output require a list of documents with are dependent + # of the app.srcdir. Add them here + + # When SPHINXDIRS is used, we just need to get index.rst, if it exists + if not os.path.samefile(doctree, app.srcdir): + doc = os.path.basename(app.srcdir) + fname = "index" + if os.path.exists(os.path.join(app.srcdir, fname + ".rst")): + latex_documents.append((fname, doc + ".tex", + "Linux %s Documentation" % doc.capitalize(), + "The kernel development community", + "manual")) + return + + # When building all docs, or when a main index.rst doesn't exist, seek + # for it on subdirectories + for doc in os.listdir(app.srcdir): + fname = os.path.join(doc, "index") + if not os.path.exists(os.path.join(app.srcdir, fname + ".rst")): + continue + + has = False + for l in latex_documents: + if l[0] == fname: + has = True + break + + if not has: + latex_documents.append((fname, doc + ".tex", + "Linux %s Documentation" % doc.capitalize(), + "The kernel development community", + "manual")) # helper # ------ @@ -102,12 +147,12 @@ extensions = [ "kernel_include", "kfigure", "maintainers_include", + "parser_yaml", "rstFlatTable", "sphinx.ext.autosectionlabel", "sphinx.ext.ifconfig", "translations", ] - # Since Sphinx version 3, the C function parser is more pedantic with regards # to type checking. Due to that, having macros at c:function cause problems. # Those needed to be escaped by using c_id_attributes[] array @@ -204,10 +249,11 @@ else: # 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 suffixes of source filenames that will be automatically parsed +source_suffix = { + ".rst": "restructuredtext", + ".yaml": "yaml", +} # The encoding of source files. # source_encoding = 'utf-8-sig' @@ -224,7 +270,7 @@ author = "The kernel development community" # |version| and |release|, also used in various other places throughout the # built documents. # -# In a normal build, version and release are are set to KERNELVERSION and +# In a normal build, version and release are set to KERNELVERSION and # KERNELRELEASE, respectively, from the Makefile via Sphinx command line # arguments. # @@ -410,19 +456,25 @@ htmlhelp_basename = "TheLinuxKerneldoc" latex_elements = { # The paper size ('letterpaper' or 'a4paper'). "papersize": "a4paper", + "passoptionstopackages": dedent(r""" + \PassOptionsToPackage{svgnames}{xcolor} + """), # The font size ('10pt', '11pt' or '12pt'). "pointsize": "11pt", + # Needed to generate a .ind file + "printindex": r"\footnotesize\raggedright\printindex", # Latex figure (float) alignment # 'figure_align': 'htbp', # Don't mangle with UTF-8 chars + "fontenc": "", "inputenc": "", "utf8extra": "", # Set document margins - "sphinxsetup": """ + "sphinxsetup": dedent(r""" hmargin=0.5in, vmargin=1in, parsedliteralwraps=true, verbatimhintsturnover=false, - """, + """), # # Some of our authors are fond of deep nesting; tell latex to # cope. @@ -430,48 +482,22 @@ latex_elements = { "maxlistdepth": "10", # For CJK One-half spacing, need to be in front of hyperref "extrapackages": r"\usepackage{setspace}", - # Additional stuff for the LaTeX preamble. - "preamble": """ - % Use some font with UTF-8 support with XeLaTeX - \\usepackage{fontspec} - \\setsansfont{DejaVu Sans} - \\setromanfont{DejaVu Serif} - \\setmonofont{DejaVu Sans Mono} - """, -} - -# Load kerneldoc specific LaTeX settings -latex_elements["preamble"] += """ + "fontpkg": dedent(r""" + \usepackage{fontspec} + \setmainfont{DejaVu Serif} + \setsansfont{DejaVu Sans} + \setmonofont{DejaVu Sans Mono} + \newfontfamily\headingfont{DejaVu Serif} + """), + "preamble": dedent(r""" % Load kerneldoc specific LaTeX settings - \\input{kerneldoc-preamble.sty} -""" + \input{kerneldoc-preamble.sty} + """) +} -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -# Sorted in alphabetical order +# This will be filled up by config-inited event latex_documents = [] -# Add all other index files from Documentation/ subdirectories -for fn in os.listdir("."): - doc = os.path.join(fn, "index") - if os.path.exists(doc + ".rst"): - has = False - for l in latex_documents: - if l[0] == doc: - has = True - break - if not has: - latex_documents.append( - ( - doc, - fn + ".tex", - "Linux %s Documentation" % fn.capitalize(), - "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 @@ -567,4 +593,4 @@ loadConfig(globals()) def setup(app): """Patterns need to be updated at init time on older Sphinx versions""" - app.connect('config-inited', update_patterns) + app.connect('config-inited', config_init) |