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