[J-u-boot.git] / doc / conf.py

# -*- coding: utf-8 -*-
#
# The U-Boot 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.
#
# 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
import sphinx

from subprocess import check_output

# Get Sphinx version
major, minor, patch = sphinx.version_info[:3]

# Set canonical URL from the Read the Docs Domain
html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")

# Tell Jinja2 templates the build is running on Read the Docs
if os.environ.get("READTHEDOCS", "") == "True":
    html_context = {
        'READTHEDOCS' : True,
    }

# 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 ------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
needs_sphinx = '2.4.4'

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
              'kfigure', 'sphinx.ext.ifconfig', # 'automarkup',
              'maintainers_include', 'sphinx.ext.autosectionlabel',
              'kernel_abi', 'kernel_feat', 'sphinx-prompt']

#
# cdomain is badly broken in Sphinx 3+.  Leaving it out generates *most*
# of the docs correctly, but not all.  Scream bloody murder but allow
# the process to proceed; hopefully somebody will fix this properly soon.
#
if major >= 3:
    if (major > 3) or (minor > 0 or patch >= 2):
        # Sphinx 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 scaped by using c_id_attributes[] array
        c_id_attributes = [
            # GCC Compiler types not parsed by Sphinx:
            "__restrict__",

            # include/linux/compiler_types.h:
            "__iomem",
            "__kernel",
            "noinstr",
            "notrace",
            "__percpu",
            "__rcu",
            "__user",

            # include/linux/compiler_attributes.h:
            "__alias",
            "__aligned",
            "__aligned_largest",
            "__always_inline",
            "__assume_aligned",
            "__cold",
            "__attribute_const__",
            "__copy",
            "__pure",
            "__designated_init",
            "__visible",
            "__printf",
            "__scanf",
            "__gnu_inline",
            "__malloc",
            "__mode",
            "__no_caller_saved_registers",
            "__noclone",
            "__nonstring",
            "__noreturn",
            "__packed",
            "__pure",
            "__section",
            "__always_unused",
            "__maybe_unused",
            "__used",
            "__weak",
            "noinline",

            # include/efi.h
            "EFIAPI",

            # include/efi_loader.h
            "__efi_runtime",

            # include/linux/memblock.h:
            "__init_memblock",
            "__meminit",

            # include/linux/init.h:
            "__init",
            "__ref",

            # include/linux/linkage.h:
            "asmlinkage",
        ]

else:
    extensions.append('cdomain')

# Ensure that autosectionlabel will produce unique names
autosectionlabel_prefix_document = True
autosectionlabel_maxdepth = 2

extensions.append("sphinx.ext.imgmath")

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_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'

# General information about the project.
project = 'Das U-Boot'
copyright = 'The U-Boot development community'
author = 'The U-Boot 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.
#
# In a normal build, version and release are are set to KERNELVERSION and
# KERNELRELEASE, respectively, from the Makefile via Sphinx command line
# arguments.
#
# The following code tries to extract the information by reading the Makefile,
# when Sphinx is run directly (e.g. by Read the Docs).
try:
    makefile_version = None
    makefile_patchlevel = None
    for line in open('../Makefile'):
        key, val = [x.strip() for x in line.split('=', 2)]
        if key == 'VERSION':
            makefile_version = val
        elif key == 'PATCHLEVEL':
            makefile_patchlevel = val
        if makefile_version and makefile_patchlevel:
            break
except:
    pass
finally:
    if makefile_version and makefile_patchlevel:
        version = release = makefile_version + '.' + makefile_patchlevel
    else:
        version = release = "unknown version"

# 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 = 'en'

# 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 = 'none'

# -- Options for HTML output ----------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.

# The Read the Docs theme is available from
# - https://github.com/snide/sphinx_rtd_theme
# - https://pypi.python.org/pypi/sphinx_rtd_theme
# - python-sphinx-rtd-theme package (on Debian)
try:
    import sphinx_rtd_theme
    html_theme = 'sphinx_rtd_theme'
    extensions.append('sphinx_rtd_theme')
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 = '../tools/logos/u-boot_logo.svg'

# 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 = False

# 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'

# Output file base name for HTML help builder.
htmlhelp_basename = 'TheUBootdoc'

# -- Options for LaTeX output ---------------------------------------------

latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    'papersize': 'a4paper',

    # The font size ('10pt', '11pt' or '12pt').
    'pointsize': '11pt',

    # Latex figure (float) alignment
    #'figure_align': 'htbp',

    # Don't mangle with UTF-8 chars
    'inputenc': '',
    'utf8extra': '',

    # Set document margins
    'sphinxsetup': '''
        hmargin=0.5in, vmargin=1in,
        parsedliteralwraps=true,
        verbatimhintsturnover=false,
    ''',

    # 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}
     ''',
}

# At least one book (translations) may have Asian characters
# with are only displayed if xeCJK is used

cjk_cmd = check_output(['fc-list', '--format="%{family[0]}\n"']).decode('utf-8', 'ignore')
if cjk_cmd.find("Noto Sans CJK SC") >= 0:
    print ("enabling CJK for LaTeX builder")
    latex_elements['preamble']  += '''
	% This is needed for translations
        \\usepackage{xeCJK}
        \\setCJKmainfont{Noto Sans CJK SC}
     '''

# With Sphinx 1.6, it is possible to change the Bg color directly
# by using:
#	\definecolor{sphinxnoteBgColor}{RGB}{204,255,255}
#	\definecolor{sphinxwarningBgColor}{RGB}{255,204,204}
#	\definecolor{sphinxattentionBgColor}{RGB}{255,255,204}
#	\definecolor{sphinximportantBgColor}{RGB}{192,255,204}
#
# However, it require to use sphinx heavy box with:
#
#	\renewenvironment{sphinxlightbox} {%
#		\\begin{sphinxheavybox}
#	}
#		\\end{sphinxheavybox}
#	}
#
# Unfortunately, the implementation is buggy: if a note is inside a
# table, it isn't displayed well. So, for now, let's use boring
# black and white notes.

# 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
latex_documents = [
    ('index', 'u-boot-hacker-manual.tex', 'U-Boot Hacker Manual',
     'The U-Boot development community', 'manual'),
]

# 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',
                                    'U-Boot %s Documentation' % fn.capitalize(),
                                    'The U-Boot 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 ---------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
    (master_doc, 'u-boot', 'The U-Boot Documentation',
     [author], 1)
]

# If true, show URL addresses after external links.
#man_show_urls = False


# -- 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, 'u-boot', 'The U-Boot Documentation',
     author, 'U-Boot', 'Boot loader for embedded systems',
     'Miscellaneous'),
]

# 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

#=======
# rst2pdf
#
# Grouping the document tree into PDF files. List of tuples
# (source start file, target name, title, author, options).
#
# See the Sphinx chapter of https://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 = [
    ('uboot-documentation', u'U-Boot', u'U-Boot', u'J. Random Bozo'),
]

# 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
# line arguments.
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())
Commit	Line	Data
78a88f79 MS	1	# -- coding: utf-8 --
	2	#
	3	# The U-Boot documentation build configuration file, created by
	4	# sphinx-quickstart on Fri Feb 12 13:51:46 2016.
	5	#
	6	# This file is execfile()d with the current directory set to its
	7	# containing dir.
	8	#
	9	# Note that not all possible configuration values are present in this
	10	# autogenerated file.
	11	#
	12	# All configuration values have a default; values that are commented out
	13	# serve to show the default.
	14
	15	import sys
	16	import os
	17	import sphinx
	18
98f01cf7 HS	19	from subprocess import check_output
98f01cf7 HS	20
78a88f79 MS	21	# Get Sphinx version
	22	major, minor, patch = sphinx.version_info[:3]
	23
df867960 HS	24	# Set canonical URL from the Read the Docs Domain
	25	html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
	26
	27	# Tell Jinja2 templates the build is running on Read the Docs
	28	if os.environ.get("READTHEDOCS", "") == "True":
d353e30e HS	29	html_context = {
	30	'READTHEDOCS' : True,
	31	}
78a88f79 MS	32
	33	# If extensions (or modules to document with autodoc) are in another directory,
	34	# add these directories to sys.path here. If the directory is relative to the
	35	# documentation root, use os.path.abspath to make it absolute, like shown here.
	36	sys.path.insert(0, os.path.abspath('sphinx'))
	37	from load_config import loadConfig
	38
	39	# -- General configuration ------------------------------------------------
	40
	41	# If your documentation needs a minimal Sphinx version, state it here.
b2a1d6b2	42	needs_sphinx = '2.4.4'
78a88f79 MS	43
	44	# Add any Sphinx extension module names here, as strings. They can be
	45	# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
	46	# ones.
98f01cf7 HS	47	extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
	48	'kfigure', 'sphinx.ext.ifconfig', # 'automarkup',
	49	'maintainers_include', 'sphinx.ext.autosectionlabel',
1cfcc229	50	'kernel_abi', 'kernel_feat', 'sphinx-prompt']
ae2b48e8 HS	51
ae2b48e8 HS	52	#
98f01cf7 HS	53	# cdomain is badly broken in Sphinx 3+. Leaving it out generates most
	54	# of the docs correctly, but not all. Scream bloody murder but allow
	55	# the process to proceed; hopefully somebody will fix this properly soon.
ae2b48e8 HS	56	#
	57	if major >= 3:
	58	if (major > 3) or (minor > 0 or patch >= 2):
ae2b48e8 HS	59	# Sphinx c function parser is more pedantic with regards to type
ae2b48e8 HS	60	# checking. Due to that, having macros at c:function cause problems.
98f01cf7	61	# Those needed to be scaped by using c_id_attributes[] array
ae2b48e8	62	c_id_attributes = [
98f01cf7 HS	63	# GCC Compiler types not parsed by Sphinx:
	64	"__restrict__",
	65
	66	# include/linux/compiler_types.h:
	67	"__iomem",
	68	"__kernel",
	69	"noinstr",
	70	"notrace",
	71	"__percpu",
	72	"__rcu",
	73	"__user",
	74
	75	# include/linux/compiler_attributes.h:
	76	"__alias",
	77	"__aligned",
	78	"__aligned_largest",
	79	"__always_inline",
	80	"__assume_aligned",
	81	"__cold",
	82	"__attribute_const__",
	83	"__copy",
	84	"__pure",
	85	"__designated_init",
	86	"__visible",
	87	"__printf",
	88	"__scanf",
	89	"__gnu_inline",
	90	"__malloc",
	91	"__mode",
	92	"__no_caller_saved_registers",
	93	"__noclone",
	94	"__nonstring",
	95	"__noreturn",
	96	"__packed",
	97	"__pure",
	98	"__section",
	99	"__always_unused",
ae2b48e8	100	"__maybe_unused",
98f01cf7 HS	101	"__used",
	102	"__weak",
	103	"noinline",
ae2b48e8 HS	104
	105	# include/efi.h
	106	"EFIAPI",
	107
	108	# include/efi_loader.h
	109	"__efi_runtime",
98f01cf7 HS	110
	111	# include/linux/memblock.h:
	112	"__init_memblock",
	113	"__meminit",
	114
	115	# include/linux/init.h:
	116	"__init",
	117	"__ref",
	118
	119	# include/linux/linkage.h:
	120	"asmlinkage",
ae2b48e8 HS	121	]
	122
	123	else:
	124	extensions.append('cdomain')
98f01cf7 HS	125
	126	# Ensure that autosectionlabel will produce unique names
	127	autosectionlabel_prefix_document = True
	128	autosectionlabel_maxdepth = 2
78a88f79	129
b2a1d6b2	130	extensions.append("sphinx.ext.imgmath")
78a88f79 MS	131
	132	# Add any paths that contain templates here, relative to this directory.
	133	templates_path = ['_templates']
	134
	135	# The suffix(es) of source filenames.
	136	# You can specify multiple suffix as a list of string:
	137	# source_suffix = ['.rst', '.md']
	138	source_suffix = '.rst'
	139
	140	# The encoding of source files.
	141	#source_encoding = 'utf-8-sig'
	142
	143	# The master toctree document.
	144	master_doc = 'index'
	145
	146	# General information about the project.
611e7f86 HS	147	project = 'Das U-Boot'
	148	copyright = 'The U-Boot development community'
	149	author = 'The U-Boot development community'
78a88f79 MS	150
	151	# The version info for the project you're documenting, acts as replacement for
	152	# \|version\| and \|release\|, also used in various other places throughout the
	153	# built documents.
	154	#
	155	# In a normal build, version and release are are set to KERNELVERSION and
	156	# KERNELRELEASE, respectively, from the Makefile via Sphinx command line
	157	# arguments.
	158	#
	159	# The following code tries to extract the information by reading the Makefile,
	160	# when Sphinx is run directly (e.g. by Read the Docs).
	161	try:
	162	makefile_version = None
	163	makefile_patchlevel = None
	164	for line in open('../Makefile'):
	165	key, val = [x.strip() for x in line.split('=', 2)]
	166	if key == 'VERSION':
	167	makefile_version = val
	168	elif key == 'PATCHLEVEL':
	169	makefile_patchlevel = val
	170	if makefile_version and makefile_patchlevel:
	171	break
	172	except:
	173	pass
	174	finally:
	175	if makefile_version and makefile_patchlevel:
	176	version = release = makefile_version + '.' + makefile_patchlevel
	177	else:
	178	version = release = "unknown version"
	179
	180	# The language for content autogenerated by Sphinx. Refer to documentation
	181	# for a list of supported languages.
	182	#
	183	# This is also used if you do content translation via gettext catalogs.
	184	# Usually you set "language" from the command line for these cases.
2b94359e	185	language = 'en'
78a88f79 MS	186
	187	# There are two options for replacing \|today\|: either, you set today to some
	188	# non-false value, then it is used:
	189	#today = ''
	190	# Else, today_fmt is used as the format for a strftime call.
	191	#today_fmt = '%B %d, %Y'
	192
	193	# List of patterns, relative to source directory, that match files and
	194	# directories to ignore when looking for source files.
	195	exclude_patterns = ['output']
	196
	197	# The reST default role (used for this markup: `text`) to use for all
	198	# documents.
	199	#default_role = None
	200
	201	# If true, '()' will be appended to :func: etc. cross-reference text.
	202	#add_function_parentheses = True
	203
	204	# If true, the current module name will be prepended to all description
	205	# unit titles (such as .. function::).
	206	#add_module_names = True
	207
	208	# If true, sectionauthor and moduleauthor directives will be shown in the
	209	# output. They are ignored by default.
	210	#show_authors = False
	211
	212	# The name of the Pygments (syntax highlighting) style to use.
	213	pygments_style = 'sphinx'
	214
	215	# A list of ignored prefixes for module index sorting.
	216	#modindex_common_prefix = []
	217
	218	# If true, keep warnings as "system message" paragraphs in the built documents.
	219	#keep_warnings = False
	220
	221	# If true, `todo` and `todoList` produce output, else they produce nothing.
	222	todo_include_todos = False
	223
	224	primary_domain = 'c'
	225	highlight_language = 'none'
	226
	227	# -- Options for HTML output ----------------------------------------------
	228
	229	# The theme to use for HTML and HTML Help pages. See the documentation for
	230	# a list of builtin themes.
	231
	232	# The Read the Docs theme is available from
	233	# - https://github.com/snide/sphinx_rtd_theme
	234	# - https://pypi.python.org/pypi/sphinx_rtd_theme
	235	# - python-sphinx-rtd-theme package (on Debian)
	236	try:
	237	import sphinx_rtd_theme
	238	html_theme = 'sphinx_rtd_theme'
31a221d3	239	extensions.append('sphinx_rtd_theme')
78a88f79 MS	240	except ImportError:
	241	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')
	242
	243	# Theme options are theme-specific and customize the look and feel of a theme
	244	# further. For a list of options available for each theme, see the
	245	# documentation.
	246	#html_theme_options = {}
	247
	248	# Add any paths that contain custom themes here, relative to this directory.
	249	#html_theme_path = []
	250
	251	# The name for this set of Sphinx documents. If None, it defaults to
	252	# "<project> v<release> documentation".
	253	#html_title = None
	254
	255	# A shorter title for the navigation bar. Default is the same as html_title.
	256	#html_short_title = None
	257
	258	# The name of an image file (relative to this directory) to place at the top
	259	# of the sidebar.
611e7f86	260	html_logo = '../tools/logos/u-boot_logo.svg'
78a88f79 MS	261
	262	# The name of an image file (within the static path) to use as favicon of the
	263	# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
	264	# pixels large.
	265	#html_favicon = None
	266
	267	# Add any paths that contain custom static files (such as style sheets) here,
	268	# relative to this directory. They are copied after the builtin static files,
	269	# so a file named "default.css" will overwrite the builtin "default.css".
	270
	271	html_static_path = ['sphinx-static']
	272
	273	html_context = {
	274	'css_files': [
	275	'_static/theme_overrides.css',
	276	],
	277	}
	278
	279	# Add any extra paths that contain custom files (such as robots.txt or
	280	# .htaccess) here, relative to this directory. These files are copied
	281	# directly to the root of the documentation.
	282	#html_extra_path = []
	283
	284	# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
	285	# using the given strftime format.
	286	#html_last_updated_fmt = '%b %d, %Y'
	287
	288	# If true, SmartyPants will be used to convert quotes and dashes to
	289	# typographically correct entities.
98f01cf7	290	html_use_smartypants = False
78a88f79 MS	291
	292	# Custom sidebar templates, maps document names to template names.
	293	#html_sidebars = {}
	294
	295	# Additional templates that should be rendered to pages, maps page names to
	296	# template names.
	297	#html_additional_pages = {}
	298
	299	# If false, no module index is generated.
	300	#html_domain_indices = True
	301
	302	# If false, no index is generated.
	303	#html_use_index = True
	304
	305	# If true, the index is split into individual pages for each letter.
	306	#html_split_index = False
	307
	308	# If true, links to the reST sources are added to the pages.
	309	#html_show_sourcelink = True
	310
	311	# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
	312	#html_show_sphinx = True
	313
	314	# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
	315	#html_show_copyright = True
	316
	317	# If true, an OpenSearch description file will be output, and all pages will
	318	# contain a <link> tag referring to it. The value of this option must be the
	319	# base URL from which the finished HTML is served.
	320	#html_use_opensearch = ''
	321
	322	# This is the file name suffix for HTML files (e.g. ".xhtml").
	323	#html_file_suffix = None
	324
	325	# Language to be used for generating the HTML full-text search index.
	326	# Sphinx supports the following languages:
	327	# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
	328	# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
	329	#html_search_language = 'en'
	330
	331	# A dictionary with options for the search language support, empty by default.
	332	# Now only 'ja' uses this config value
	333	#html_search_options = {'type': 'default'}
	334
	335	# The name of a javascript file (relative to the configuration directory) that
	336	# implements a search results scorer. If empty, the default will be used.
	337	#html_search_scorer = 'scorer.js'
	338
	339	# Output file base name for HTML help builder.
611e7f86	340	htmlhelp_basename = 'TheUBootdoc'
78a88f79 MS	341
	342	# -- Options for LaTeX output ---------------------------------------------
	343
	344	latex_elements = {
00e80da9 HS	345	# The paper size ('letterpaper' or 'a4paper').
00e80da9 HS	346	'papersize': 'a4paper',
78a88f79	347
00e80da9 HS	348	# The font size ('10pt', '11pt' or '12pt').
00e80da9 HS	349	'pointsize': '11pt',
78a88f79	350
00e80da9 HS	351	# Latex figure (float) alignment
00e80da9 HS	352	#'figure_align': 'htbp',
78a88f79	353
00e80da9 HS	354	# Don't mangle with UTF-8 chars
	355	'inputenc': '',
	356	'utf8extra': '',
78a88f79	357
00e80da9 HS	358	# Set document margins
	359	'sphinxsetup': '''
	360	hmargin=0.5in, vmargin=1in,
	361	parsedliteralwraps=true,
	362	verbatimhintsturnover=false,
	363	''',
	364
	365	# Additional stuff for the LaTeX preamble.
78a88f79	366	'preamble': '''
00e80da9	367	% Use some font with UTF-8 support with XeLaTeX
78a88f79	368	\\usepackage{fontspec}
98f01cf7 HS	369	\\setsansfont{DejaVu Sans}
98f01cf7 HS	370	\\setromanfont{DejaVu Serif}
78a88f79	371	\\setmonofont{DejaVu Sans Mono}
00e80da9	372	''',
e716c902	373	}
10a1df3c	374
98f01cf7 HS	375	# At least one book (translations) may have Asian characters
	376	# with are only displayed if xeCJK is used
	377
	378	cjk_cmd = check_output(['fc-list', '--format="%{family[0]}\n"']).decode('utf-8', 'ignore')
	379	if cjk_cmd.find("Noto Sans CJK SC") >= 0:
	380	print ("enabling CJK for LaTeX builder")
	381	latex_elements['preamble'] += '''
	382	% This is needed for translations
	383	\\usepackage{xeCJK}
	384	\\setCJKmainfont{Noto Sans CJK SC}
	385	'''
	386
78a88f79 MS	387	# With Sphinx 1.6, it is possible to change the Bg color directly
	388	# by using:
	389	# \definecolor{sphinxnoteBgColor}{RGB}{204,255,255}
	390	# \definecolor{sphinxwarningBgColor}{RGB}{255,204,204}
	391	# \definecolor{sphinxattentionBgColor}{RGB}{255,255,204}
	392	# \definecolor{sphinximportantBgColor}{RGB}{192,255,204}
	393	#
	394	# However, it require to use sphinx heavy box with:
	395	#
	396	# \renewenvironment{sphinxlightbox} {%
	397	# \\begin{sphinxheavybox}
	398	# }
	399	# \\end{sphinxheavybox}
	400	# }
	401	#
	402	# Unfortunately, the implementation is buggy: if a note is inside a
	403	# table, it isn't displayed well. So, for now, let's use boring
	404	# black and white notes.
	405
	406	# Grouping the document tree into LaTeX files. List of tuples
	407	# (source start file, target name, title,
	408	# author, documentclass [howto, manual, or own class]).
	409	# Sorted in alphabetical order
	410	latex_documents = [
611e7f86 HS	411	('index', 'u-boot-hacker-manual.tex', 'U-Boot Hacker Manual',
611e7f86 HS	412	'The U-Boot development community', 'manual'),
78a88f79 MS	413	]
78a88f79 MS	414
98f01cf7 HS	415	# Add all other index files from Documentation/ subdirectories
	416	for fn in os.listdir('.'):
	417	doc = os.path.join(fn, "index")
	418	if os.path.exists(doc + ".rst"):
	419	has = False
	420	for l in latex_documents:
	421	if l[0] == doc:
	422	has = True
	423	break
	424	if not has:
	425	latex_documents.append((doc, fn + '.tex',
611e7f86 HS	426	'U-Boot %s Documentation' % fn.capitalize(),
611e7f86 HS	427	'The U-Boot development community',
98f01cf7 HS	428	'manual'))
98f01cf7 HS	429
78a88f79 MS	430	# The name of an image file (relative to this directory) to place at the top of
	431	# the title page.
	432	#latex_logo = None
	433
	434	# For "manual" documents, if this is true, then toplevel headings are parts,
	435	# not chapters.
	436	#latex_use_parts = False
	437
	438	# If true, show page references after internal links.
	439	#latex_show_pagerefs = False
	440
	441	# If true, show URL addresses after external links.
	442	#latex_show_urls = False
	443
	444	# Documents to append as an appendix to all manuals.
	445	#latex_appendices = []
	446
	447	# If false, no module index is generated.
	448	#latex_domain_indices = True
	449
	450
	451	# -- Options for manual page output ---------------------------------------
	452
	453	# One entry per manual page. List of tuples
	454	# (source start file, name, description, authors, manual section).
	455	man_pages = [
7fa4c27a	456	(master_doc, 'u-boot', 'The U-Boot Documentation',
78a88f79 MS	457	[author], 1)
	458	]
	459
	460	# If true, show URL addresses after external links.
	461	#man_show_urls = False
	462
	463
	464	# -- Options for Texinfo output -------------------------------------------
	465
	466	# Grouping the document tree into Texinfo files. List of tuples
	467	# (source start file, target name, title, author,
	468	# dir menu entry, description, category)
	469	texinfo_documents = [
7fa4c27a MC	470	(master_doc, 'u-boot', 'The U-Boot Documentation',
7fa4c27a MC	471	author, 'U-Boot', 'Boot loader for embedded systems',
78a88f79 MS	472	'Miscellaneous'),
	473	]
	474
	475	# Documents to append as an appendix to all manuals.
	476	#texinfo_appendices = []
	477
	478	# If false, no module index is generated.
	479	#texinfo_domain_indices = True
	480
	481	# How to display URL addresses: 'footnote', 'no', or 'inline'.
	482	#texinfo_show_urls = 'footnote'
	483
	484	# If true, do not generate a @detailmenu in the "Top" node's menu.
	485	#texinfo_no_detailmenu = False
	486
	487
	488	# -- Options for Epub output ----------------------------------------------
	489
	490	# Bibliographic Dublin Core info.
	491	epub_title = project
	492	epub_author = author
	493	epub_publisher = author
	494	epub_copyright = copyright
	495
	496	# The basename for the epub file. It defaults to the project name.
	497	#epub_basename = project
	498
	499	# The HTML theme for the epub output. Since the default themes are not
	500	# optimized for small screen space, using the same theme for HTML and epub
	501	# output is usually not wise. This defaults to 'epub', a theme designed to save
	502	# visual space.
	503	#epub_theme = 'epub'
	504
	505	# The language of the text. It defaults to the language option
	506	# or 'en' if the language is not set.
	507	#epub_language = ''
	508
	509	# The scheme of the identifier. Typical schemes are ISBN or URL.
	510	#epub_scheme = ''
	511
	512	# The unique identifier of the text. This can be a ISBN number
	513	# or the project homepage.
	514	#epub_identifier = ''
	515
	516	# A unique identification for the text.
	517	#epub_uid = ''
	518
	519	# A tuple containing the cover image and cover page html template filenames.
	520	#epub_cover = ()
	521
	522	# A sequence of (type, uri, title) tuples for the guide element of content.opf.
	523	#epub_guide = ()
	524
	525	# HTML files that should be inserted before the pages created by sphinx.
	526	# The format is a list of tuples containing the path and title.
	527	#epub_pre_files = []
	528
	529	# HTML files that should be inserted after the pages created by sphinx.
	530	# The format is a list of tuples containing the path and title.
	531	#epub_post_files = []
	532
	533	# A list of files that should not be packed into the epub file.
	534	epub_exclude_files = ['search.html']
	535
536	# The depth of the table of contents in toc.ncx.
537	#epub_tocdepth = 3
538
539	# Allow duplicate toc entries.
540	#epub_tocdup = True
541
542	# Choose between 'default' and 'includehidden'.
543	#epub_tocscope = 'default'
544
545	# Fix unsupported image types using the Pillow.
546	#epub_fix_images = False
547
548	# Scale large images.
549	#epub_max_image_width = 0
550
551	# How to display URL addresses: 'footnote', 'no', or 'inline'.
552	#epub_show_urls = 'inline'
553
554	# If false, no index is generated.
555	#epub_use_index = True
556
557	#=======
558	# rst2pdf
559	#
560	# Grouping the document tree into PDF files. List of tuples
561	# (source start file, target name, title, author, options).
562	#
98f01cf7	563	# See the Sphinx chapter of https://ralsina.me/static/manual.pdf
78a88f79 MS	564	#
	565	# FIXME: Do not add the index file here; the result will be too big. Adding
	566	# multiple PDF files here actually tries to get the cross-referencing right
	567	# between PDF files.
	568	pdf_documents = [
611e7f86	569	('uboot-documentation', u'U-Boot', u'U-Boot', u'J. Random Bozo'),
78a88f79 MS	570	]
	571
	572	# kernel-doc extension configuration for running Sphinx directly (e.g. by Read
	573	# the Docs). In a normal build, these are supplied from the Makefile via command
	574	# line arguments.
	575	kerneldoc_bin = '../scripts/kernel-doc'
	576	kerneldoc_srctree = '..'
	577
	578	# ------------------------------------------------------------------------------
	579	# Since loadConfig overwrites settings from the global namespace, it has to be
	580	# the last statement in the conf.py file
	581	# ------------------------------------------------------------------------------
	582	loadConfig(globals())