docs: conf.py: several coding style fixes

+173 -180

1 changed file

expand all

Documentation

conf.py

+173 -180

Documentation/conf.py

··· 1 - # -*- coding: utf-8 -*- 2 - # 3 - # The Linux Kernel 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. 1 + # SPDX-License-Identifier: GPL-2.0-only 2 + # pylint: disable=C0103,C0209 14 3 15 - import sys 4 + """ 5 + The Linux Kernel documentation build configuration file. 6 + """ 7 + 16 8 import os 17 - import sphinx 18 9 import shutil 10 + import sys 11 + 12 + import sphinx 13 + 14 + # If extensions (or modules to document with autodoc) are in another directory, 15 + # add these directories to sys.path here. If the directory is relative to the 16 + # documentation root, use os.path.abspath to make it absolute, like shown here. 17 + sys.path.insert(0, os.path.abspath("sphinx")) 18 + 19 + from load_config import loadConfig # pylint: disable=C0413,E0401 20 + 21 + # Minimal supported version 22 + needs_sphinx = "3.4.3" 19 23 20 24 # Get Sphinx version 21 - major, minor, patch = sphinx.version_info[:3] 25 + major, minor, patch = sphinx.version_info[:3] # pylint: disable=I1101 22 26 23 27 # Include_patterns were added on Sphinx 5.1 24 28 if (major < 5) or (major == 5 and minor < 1): ··· 30 26 else: 31 27 has_include_patterns = True 32 28 # Include patterns that don't contain directory names, in glob format 33 - include_patterns = ['**.rst'] 29 + include_patterns = ["**.rst"] 34 30 35 31 # Location of Documentation/ directory 36 - doctree = os.path.abspath('.') 32 + doctree = os.path.abspath(".") 37 33 38 34 # Exclude of patterns that don't contain directory names, in glob format. 39 35 exclude_patterns = [] 40 36 41 37 # List of patterns that contain directory names in glob format. 42 38 dyn_include_patterns = [] 43 - dyn_exclude_patterns = ['output'] 39 + dyn_exclude_patterns = ["output"] 44 40 45 41 # Properly handle include/exclude patterns 46 42 # ---------------------------------------- 47 43 48 44 def update_patterns(app, config): 49 - 50 45 """ 51 46 On Sphinx, all directories are relative to what it is passed as 52 47 SOURCEDIR parameter for sphinx-build. Due to that, all patterns ··· 56 53 exclude relative patterns that start with "../". 57 54 """ 58 55 59 - sourcedir = app.srcdir # full path to the source directory 60 - builddir = os.environ.get("BUILDDIR") 61 - 62 56 # setup include_patterns dynamically 63 57 if has_include_patterns: 64 58 for p in dyn_include_patterns: 65 59 full = os.path.join(doctree, p) 66 60 67 - rel_path = os.path.relpath(full, start = app.srcdir) 61 + rel_path = os.path.relpath(full, start=app.srcdir) 68 62 if rel_path.startswith("../"): 69 63 continue 70 64 ··· 71 71 for p in dyn_exclude_patterns: 72 72 full = os.path.join(doctree, p) 73 73 74 - rel_path = os.path.relpath(full, start = app.srcdir) 74 + rel_path = os.path.relpath(full, start=app.srcdir) 75 75 if rel_path.startswith("../"): 76 76 continue 77 77 78 78 config.exclude_patterns.append(rel_path) 79 79 80 + 80 81 # helper 81 82 # ------ 83 + 82 84 83 85 def have_command(cmd): 84 86 """Search ``cmd`` in the ``PATH`` environment. ··· 90 88 """ 91 89 return shutil.which(cmd) is not None 92 90 93 - # If extensions (or modules to document with autodoc) are in another directory, 94 - # add these directories to sys.path here. If the directory is relative to the 95 - # documentation root, use os.path.abspath to make it absolute, like shown here. 96 - sys.path.insert(0, os.path.abspath('sphinx')) 97 - from load_config import loadConfig 98 91 99 92 # -- General configuration ------------------------------------------------ 100 93 101 - # If your documentation needs a minimal Sphinx version, state it here. 102 - needs_sphinx = '3.4.3' 103 - 104 - # Add any Sphinx extension module names here, as strings. They can be 105 - # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 106 - # ones. 107 - extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 108 - 'kfigure', 'sphinx.ext.ifconfig', 'automarkup', 109 - 'maintainers_include', 'sphinx.ext.autosectionlabel', 110 - 'kernel_abi', 'kernel_feat', 'translations'] 94 + # Add any Sphinx extensions in alphabetic order 95 + extensions = [ 96 + "automarkup", 97 + "kernel_abi", 98 + "kerneldoc", 99 + "kernel_feat", 100 + "kernel_include", 101 + "kfigure", 102 + "maintainers_include", 103 + "rstFlatTable", 104 + "sphinx.ext.autosectionlabel", 105 + "sphinx.ext.ifconfig", 106 + "translations", 107 + ] 111 108 112 109 # Since Sphinx version 3, the C function parser is more pedantic with regards 113 110 # to type checking. Due to that, having macros at c:function cause problems. ··· 181 180 # Load math renderer: 182 181 # For html builder, load imgmath only when its dependencies are met. 183 182 # mathjax is the default math renderer since Sphinx 1.8. 184 - have_latex = have_command('latex') 185 - have_dvipng = have_command('dvipng') 183 + have_latex = have_command("latex") 184 + have_dvipng = have_command("dvipng") 186 185 load_imgmath = have_latex and have_dvipng 187 186 188 187 # Respect SPHINX_IMGMATH (for html docs only) 189 - if 'SPHINX_IMGMATH' in os.environ: 190 - env_sphinx_imgmath = os.environ['SPHINX_IMGMATH'] 191 - if 'yes' in env_sphinx_imgmath: 188 + if "SPHINX_IMGMATH" in os.environ: 189 + env_sphinx_imgmath = os.environ["SPHINX_IMGMATH"] 190 + if "yes" in env_sphinx_imgmath: 192 191 load_imgmath = True 193 - elif 'no' in env_sphinx_imgmath: 192 + elif "no" in env_sphinx_imgmath: 194 193 load_imgmath = False 195 194 else: 196 195 sys.stderr.write("Unknown env SPHINX_IMGMATH=%s ignored.\n" % env_sphinx_imgmath) 197 196 198 197 if load_imgmath: 199 198 extensions.append("sphinx.ext.imgmath") 200 - math_renderer = 'imgmath' 199 + math_renderer = "imgmath" 201 200 else: 202 - math_renderer = 'mathjax' 201 + math_renderer = "mathjax" 203 202 204 203 # Add any paths that contain templates here, relative to this directory. 205 - templates_path = ['sphinx/templates'] 204 + templates_path = ["sphinx/templates"] 206 205 207 206 # The suffix(es) of source filenames. 208 207 # You can specify multiple suffix as a list of string: ··· 210 209 source_suffix = '.rst' 211 210 212 211 # The encoding of source files. 213 - #source_encoding = 'utf-8-sig' 212 + # source_encoding = 'utf-8-sig' 214 213 215 214 # The master toctree document. 216 - master_doc = 'index' 215 + master_doc = "index" 217 216 218 217 # General information about the project. 219 - project = 'The Linux Kernel' 220 - copyright = 'The kernel development community' 221 - author = 'The kernel development community' 218 + project = "The Linux Kernel" 219 + copyright = "The kernel development community" # pylint: disable=W0622 220 + author = "The kernel development community" 222 221 223 222 # The version info for the project you're documenting, acts as replacement for 224 223 # |version| and |release|, also used in various other places throughout the ··· 233 232 try: 234 233 makefile_version = None 235 234 makefile_patchlevel = None 236 - for line in open('../Makefile'): 237 - key, val = [x.strip() for x in line.split('=', 2)] 238 - if key == 'VERSION': 239 - makefile_version = val 240 - elif key == 'PATCHLEVEL': 241 - makefile_patchlevel = val 242 - if makefile_version and makefile_patchlevel: 243 - break 244 - except: 235 + with open("../Makefile", encoding="utf=8") as fp: 236 + for line in fp: 237 + key, val = [x.strip() for x in line.split("=", 2)] 238 + if key == "VERSION": 239 + makefile_version = val 240 + elif key == "PATCHLEVEL": 241 + makefile_patchlevel = val 242 + if makefile_version and makefile_patchlevel: 243 + break 244 + except Exception: 245 245 pass 246 246 finally: 247 247 if makefile_version and makefile_patchlevel: 248 - version = release = makefile_version + '.' + makefile_patchlevel 248 + version = release = makefile_version + "." + makefile_patchlevel 249 249 else: 250 250 version = release = "unknown version" 251 251 252 - # 253 - # HACK: there seems to be no easy way for us to get at the version and 254 - # release information passed in from the makefile...so go pawing through the 255 - # command-line options and find it for ourselves. 256 - # 252 + 257 253 def get_cline_version(): 258 - c_version = c_release = '' 254 + """ 255 + HACK: There seems to be no easy way for us to get at the version and 256 + release information passed in from the makefile...so go pawing through the 257 + command-line options and find it for ourselves. 258 + """ 259 + 260 + c_version = c_release = "" 259 261 for arg in sys.argv: 260 - if arg.startswith('version='): 262 + if arg.startswith("version="): 261 263 c_version = arg[8:] 262 - elif arg.startswith('release='): 264 + elif arg.startswith("release="): 263 265 c_release = arg[8:] 264 266 if c_version: 265 267 if c_release: 266 - return c_version + '-' + c_release 268 + return c_version + "-" + c_release 267 269 return c_version 268 - return version # Whatever we came up with before 270 + return version # Whatever we came up with before 271 + 269 272 270 273 # The language for content autogenerated by Sphinx. Refer to documentation 271 274 # for a list of supported languages. 272 275 # 273 276 # This is also used if you do content translation via gettext catalogs. 274 277 # Usually you set "language" from the command line for these cases. 275 - language = 'en' 278 + language = "en" 276 279 277 280 # There are two options for replacing |today|: either, you set today to some 278 281 # non-false value, then it is used: 279 - #today = '' 282 + # today = '' 280 283 # Else, today_fmt is used as the format for a strftime call. 281 - #today_fmt = '%B %d, %Y' 284 + # today_fmt = '%B %d, %Y' 282 285 283 286 # The reST default role (used for this markup: `text`) to use for all 284 287 # documents. 285 - #default_role = None 288 + # default_role = None 286 289 287 290 # If true, '()' will be appended to :func: etc. cross-reference text. 288 - #add_function_parentheses = True 291 + # add_function_parentheses = True 289 292 290 293 # If true, the current module name will be prepended to all description 291 294 # unit titles (such as .. function::). 292 - #add_module_names = True 295 + # add_module_names = True 293 296 294 297 # If true, sectionauthor and moduleauthor directives will be shown in the 295 298 # output. They are ignored by default. 296 - #show_authors = False 299 + # show_authors = False 297 300 298 301 # The name of the Pygments (syntax highlighting) style to use. 299 - pygments_style = 'sphinx' 302 + pygments_style = "sphinx" 300 303 301 304 # A list of ignored prefixes for module index sorting. 302 - #modindex_common_prefix = [] 305 + # modindex_common_prefix = [] 303 306 304 307 # If true, keep warnings as "system message" paragraphs in the built documents. 305 - #keep_warnings = False 308 + # keep_warnings = False 306 309 307 310 # If true, `todo` and `todoList` produce output, else they produce nothing. 308 311 todo_include_todos = False 309 312 310 - primary_domain = 'c' 311 - highlight_language = 'none' 313 + primary_domain = "c" 314 + highlight_language = "none" 312 315 313 316 # -- Options for HTML output ---------------------------------------------- 314 317 ··· 320 315 # a list of builtin themes. 321 316 322 317 # Default theme 323 - html_theme = 'alabaster' 318 + html_theme = "alabaster" 324 319 html_css_files = [] 325 320 326 321 if "DOCS_THEME" in os.environ: 327 322 html_theme = os.environ["DOCS_THEME"] 328 323 329 - if html_theme == 'sphinx_rtd_theme' or html_theme == 'sphinx_rtd_dark_mode': 324 + if html_theme in ["sphinx_rtd_theme", "sphinx_rtd_dark_mode"]: 330 325 # Read the Docs theme 331 326 try: 332 327 import sphinx_rtd_theme 328 + 333 329 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] 334 330 335 331 # Add any paths that contain custom static files (such as style sheets) here, 336 332 # relative to this directory. They are copied after the builtin static files, 337 333 # so a file named "default.css" will overwrite the builtin "default.css". 338 334 html_css_files = [ 339 - 'theme_overrides.css', 335 + "theme_overrides.css", 340 336 ] 341 337 342 338 # Read the Docs dark mode override theme 343 - if html_theme == 'sphinx_rtd_dark_mode': 339 + if html_theme == "sphinx_rtd_dark_mode": 344 340 try: 345 - import sphinx_rtd_dark_mode 346 - extensions.append('sphinx_rtd_dark_mode') 347 - except ImportError: 348 - html_theme == 'sphinx_rtd_theme' 341 + import sphinx_rtd_dark_mode # pylint: disable=W0611 349 342 350 - if html_theme == 'sphinx_rtd_theme': 351 - # Add color-specific RTD normal mode 352 - html_css_files.append('theme_rtd_colors.css') 343 + extensions.append("sphinx_rtd_dark_mode") 344 + except ImportError: 345 + html_theme = "sphinx_rtd_theme" 346 + 347 + if html_theme == "sphinx_rtd_theme": 348 + # Add color-specific RTD normal mode 349 + html_css_files.append("theme_rtd_colors.css") 353 350 354 351 html_theme_options = { 355 - 'navigation_depth': -1, 352 + "navigation_depth": -1, 356 353 } 357 354 358 355 except ImportError: 359 - html_theme = 'alabaster' 356 + html_theme = "alabaster" 360 357 361 358 if "DOCS_CSS" in os.environ: 362 359 css = os.environ["DOCS_CSS"].split(" ") ··· 366 359 for l in css: 367 360 html_css_files.append(l) 368 361 369 - if html_theme == 'alabaster': 362 + if html_theme == "alabaster": 370 363 html_theme_options = { 371 - 'description': get_cline_version(), 372 - 'page_width': '65em', 373 - 'sidebar_width': '15em', 374 - 'fixed_sidebar': 'true', 375 - 'font_size': 'inherit', 376 - 'font_family': 'serif', 364 + "description": get_cline_version(), 365 + "page_width": "65em", 366 + "sidebar_width": "15em", 367 + "fixed_sidebar": "true", 368 + "font_size": "inherit", 369 + "font_family": "serif", 377 370 } 378 371 379 372 sys.stderr.write("Using %s theme\n" % html_theme) ··· 381 374 # Add any paths that contain custom static files (such as style sheets) here, 382 375 # relative to this directory. They are copied after the builtin static files, 383 376 # so a file named "default.css" will overwrite the builtin "default.css". 384 - html_static_path = ['sphinx-static'] 377 + html_static_path = ["sphinx-static"] 385 378 386 379 # If true, Docutils "smart quotes" will be used to convert quotes and dashes 387 380 # to typographically correct entities. However, conversion of "--" to "—" 388 381 # is not always what we want, so enable only quotes. 389 - smartquotes_action = 'q' 382 + smartquotes_action = "q" 390 383 391 384 # Custom sidebar templates, maps document names to template names. 392 385 # Note that the RTD theme ignores this 393 - html_sidebars = { '**': ['searchbox.html', 'kernel-toc.html', 'sourcelink.html']} 386 + html_sidebars = {"**": ["searchbox.html", 387 + "kernel-toc.html", 388 + "sourcelink.html"]} 394 389 395 390 # about.html is available for alabaster theme. Add it at the front. 396 - if html_theme == 'alabaster': 397 - html_sidebars['**'].insert(0, 'about.html') 391 + if html_theme == "alabaster": 392 + html_sidebars["**"].insert(0, "about.html") 398 393 399 394 # The name of an image file (relative to this directory) to place at the top 400 395 # of the sidebar. 401 - html_logo = 'images/logo.svg' 396 + html_logo = "images/logo.svg" 402 397 403 398 # Output file base name for HTML help builder. 404 - htmlhelp_basename = 'TheLinuxKerneldoc' 399 + htmlhelp_basename = "TheLinuxKerneldoc" 405 400 406 401 # -- Options for LaTeX output --------------------------------------------- 407 402 408 403 latex_elements = { 409 404 # The paper size ('letterpaper' or 'a4paper'). 410 - 'papersize': 'a4paper', 411 - 405 + "papersize": "a4paper", 412 406 # The font size ('10pt', '11pt' or '12pt'). 413 - 'pointsize': '11pt', 414 - 407 + "pointsize": "11pt", 415 408 # Latex figure (float) alignment 416 - #'figure_align': 'htbp', 417 - 409 + # 'figure_align': 'htbp', 418 410 # Don't mangle with UTF-8 chars 419 - 'inputenc': '', 420 - 'utf8extra': '', 421 - 411 + "inputenc": "", 412 + "utf8extra": "", 422 413 # Set document margins 423 - 'sphinxsetup': ''' 414 + "sphinxsetup": """ 424 415 hmargin=0.5in, vmargin=1in, 425 416 parsedliteralwraps=true, 426 417 verbatimhintsturnover=false, 427 - ''', 428 - 418 + """, 429 419 # 430 420 # Some of our authors are fond of deep nesting; tell latex to 431 421 # cope. 432 422 # 433 - 'maxlistdepth': '10', 434 - 423 + "maxlistdepth": "10", 435 424 # For CJK One-half spacing, need to be in front of hyperref 436 - 'extrapackages': r'\usepackage{setspace}', 437 - 425 + "extrapackages": r"\usepackage{setspace}", 438 426 # Additional stuff for the LaTeX preamble. 439 - 'preamble': ''' 427 + "preamble": """ 440 428 % Use some font with UTF-8 support with XeLaTeX 441 429 \\usepackage{fontspec} 442 430 \\setsansfont{DejaVu Sans} 443 431 \\setromanfont{DejaVu Serif} 444 432 \\setmonofont{DejaVu Sans Mono} 445 - ''', 433 + """, 446 434 } 447 435 448 436 # Load kerneldoc specific LaTeX settings 449 - latex_elements['preamble'] += ''' 437 + latex_elements["preamble"] += """ 450 438 % Load kerneldoc specific LaTeX settings 451 - \\input{kerneldoc-preamble.sty} 452 - ''' 453 - 454 - # With Sphinx 1.6, it is possible to change the Bg color directly 455 - # by using: 456 - # \definecolor{sphinxnoteBgColor}{RGB}{204,255,255} 457 - # \definecolor{sphinxwarningBgColor}{RGB}{255,204,204} 458 - # \definecolor{sphinxattentionBgColor}{RGB}{255,255,204} 459 - # \definecolor{sphinximportantBgColor}{RGB}{192,255,204} 460 - # 461 - # However, it require to use sphinx heavy box with: 462 - # 463 - # \renewenvironment{sphinxlightbox} {% 464 - # \\begin{sphinxheavybox} 465 - # } 466 - # \\end{sphinxheavybox} 467 - # } 468 - # 469 - # Unfortunately, the implementation is buggy: if a note is inside a 470 - # table, it isn't displayed well. So, for now, let's use boring 471 - # black and white notes. 439 + \\input{kerneldoc-preamble.sty} 440 + """ 472 441 473 442 # Grouping the document tree into LaTeX files. List of tuples 474 443 # (source start file, target name, title, 475 444 # author, documentclass [howto, manual, or own class]). 476 445 # Sorted in alphabetical order 477 - latex_documents = [ 478 - ] 446 + latex_documents = [] 479 447 480 448 # Add all other index files from Documentation/ subdirectories 481 - for fn in os.listdir('.'): 449 + for fn in os.listdir("."): 482 450 doc = os.path.join(fn, "index") 483 451 if os.path.exists(doc + ".rst"): 484 452 has = False ··· 462 480 has = True 463 481 break 464 482 if not has: 465 - latex_documents.append((doc, fn + '.tex', 466 - 'Linux %s Documentation' % fn.capitalize(), 467 - 'The kernel development community', 468 - 'manual')) 483 + latex_documents.append( 484 + ( 485 + doc, 486 + fn + ".tex", 487 + "Linux %s Documentation" % fn.capitalize(), 488 + "The kernel development community", 489 + "manual", 490 + ) 491 + ) 469 492 470 493 # The name of an image file (relative to this directory) to place at the top of 471 494 # the title page. 472 - #latex_logo = None 495 + # latex_logo = None 473 496 474 497 # For "manual" documents, if this is true, then toplevel headings are parts, 475 498 # not chapters. 476 - #latex_use_parts = False 499 + # latex_use_parts = False 477 500 478 501 # If true, show page references after internal links. 479 - #latex_show_pagerefs = False 502 + # latex_show_pagerefs = False 480 503 481 504 # If true, show URL addresses after external links. 482 - #latex_show_urls = False 505 + # latex_show_urls = False 483 506 484 507 # Documents to append as an appendix to all manuals. 485 - #latex_appendices = [] 508 + # latex_appendices = [] 486 509 487 510 # If false, no module index is generated. 488 - #latex_domain_indices = True 511 + # latex_domain_indices = True 489 512 490 513 # Additional LaTeX stuff to be copied to build directory 491 514 latex_additional_files = [ 492 - 'sphinx/kerneldoc-preamble.sty', 515 + "sphinx/kerneldoc-preamble.sty", 493 516 ] 494 517 495 518 ··· 503 516 # One entry per manual page. List of tuples 504 517 # (source start file, name, description, authors, manual section). 505 518 man_pages = [ 506 - (master_doc, 'thelinuxkernel', 'The Linux Kernel Documentation', 507 - [author], 1) 519 + (master_doc, "thelinuxkernel", "The Linux Kernel Documentation", [author], 1) 508 520 ] 509 521 510 522 # If true, show URL addresses after external links. 511 - #man_show_urls = False 523 + # man_show_urls = False 512 524 513 525 514 526 # -- Options for Texinfo output ------------------------------------------- ··· 515 529 # Grouping the document tree into Texinfo files. List of tuples 516 530 # (source start file, target name, title, author, 517 531 # dir menu entry, description, category) 518 - texinfo_documents = [ 519 - (master_doc, 'TheLinuxKernel', 'The Linux Kernel Documentation', 520 - author, 'TheLinuxKernel', 'One line description of project.', 521 - 'Miscellaneous'), 522 - ] 532 + texinfo_documents = [( 533 + master_doc, 534 + "TheLinuxKernel", 535 + "The Linux Kernel Documentation", 536 + author, 537 + "TheLinuxKernel", 538 + "One line description of project.", 539 + "Miscellaneous", 540 + ),] 523 541 524 542 # -- Options for Epub output ---------------------------------------------- 525 543 ··· 534 544 epub_copyright = copyright 535 545 536 546 # A list of files that should not be packed into the epub file. 537 - epub_exclude_files = ['search.html'] 547 + epub_exclude_files = ["search.html"] 538 548 539 - #======= 549 + # ======= 540 550 # rst2pdf 541 551 # 542 552 # Grouping the document tree into PDF files. List of tuples ··· 548 558 # multiple PDF files here actually tries to get the cross-referencing right 549 559 # *between* PDF files. 550 560 pdf_documents = [ 551 - ('kernel-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'), 561 + ("kernel-documentation", "Kernel", "Kernel", "J. Random Bozo"), 552 562 ] 553 563 554 564 # kernel-doc extension configuration for running Sphinx directly (e.g. by Read 555 565 # the Docs). In a normal build, these are supplied from the Makefile via command 556 566 # line arguments. 557 - kerneldoc_bin = '../scripts/kernel-doc.py' 558 - kerneldoc_srctree = '..' 567 + kerneldoc_bin = "../scripts/kernel-doc.py" 568 + kerneldoc_srctree = ".." 559 569 560 570 # ------------------------------------------------------------------------------ 561 571 # Since loadConfig overwrites settings from the global namespace, it has to be ··· 563 573 # ------------------------------------------------------------------------------ 564 574 loadConfig(globals()) 565 575 576 + 566 577 def setup(app): 578 + """Patterns need to be updated at init time on older Sphinx versions""" 579 + 567 580 app.connect('config-inited', update_patterns)

Configure Feed

Configure Feed