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