diff options
Diffstat (limited to 'doc/conf.py')
| -rw-r--r-- | doc/conf.py | 141 |
1 files changed, 28 insertions, 113 deletions
diff --git a/doc/conf.py b/doc/conf.py index 1b9f3591d5..ee7f201724 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -16,8 +16,6 @@ import sys import os import sphinx -from subprocess import check_output - # Get Sphinx version major, minor, patch = sphinx.version_info[:3] @@ -33,98 +31,39 @@ from load_config import loadConfig # If your documentation needs a minimal Sphinx version, state it here. needs_sphinx = '1.3' +latex_engine = 'xelatex' + # 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'] +extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'kfigure'] # -# 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. +# cdomain is badly broken in Sphinx 3+. Leaving it out generates *most* +# of the docs correctly, but not all. # if major >= 3: - sys.stderr.write('''WARNING: The kernel documentation build process - support for Sphinx v3.0 and above is brand new. Be prepared for - possible issues in the generated output. - ''') if (major > 3) or (minor > 0 or patch >= 2): + sys.stderr.write('''The build process with Sphinx 3+ is broken. +You will have to remove -W in doc/Makefile. +''') # 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 + # Those needed to be escaped 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", + + # include/linux/compiler.h "__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') - if major == 1 and minor < 7: - sys.stderr.write('WARNING: Sphinx 1.7 or greater will be required as of ' - 'the v2021.04 release\n') - -# Ensure that autosectionlabel will produce unique names -autosectionlabel_prefix_document = True -autosectionlabel_maxdepth = 2 # The name of the math extension changed on Sphinx 1.4 if (major == 1 and minor > 3) or (major > 1): @@ -147,9 +86,9 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = 'The Linux Kernel' -copyright = 'The kernel development community' -author = 'The kernel development community' +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 @@ -260,7 +199,7 @@ except ImportError: # The name of an image file (relative to this directory) to place at the top # of the sidebar. -#html_logo = None +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 @@ -290,7 +229,7 @@ html_context = { # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. -html_use_smartypants = False +#html_use_smartypants = True # Custom sidebar templates, maps document names to template names. #html_sidebars = {} @@ -340,7 +279,7 @@ html_use_smartypants = False #html_search_scorer = 'scorer.js' # Output file base name for HTML help builder. -htmlhelp_basename = 'TheLinuxKerneldoc' +htmlhelp_basename = 'TheUBootdoc' # -- Options for LaTeX output --------------------------------------------- @@ -349,7 +288,7 @@ latex_elements = { 'papersize': 'a4paper', # The font size ('10pt', '11pt' or '12pt'). -'pointsize': '11pt', +'pointsize': '8pt', # Latex figure (float) alignment #'figure_align': 'htbp', @@ -362,23 +301,12 @@ latex_elements = { 'preamble': ''' % Use some font with UTF-8 support with XeLaTeX \\usepackage{fontspec} - \\setsansfont{DejaVu Sans} - \\setromanfont{DejaVu Serif} + \\setsansfont{DejaVu Serif} + \\setromanfont{DejaVu Sans} \\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} ''' +} # Fix reference escape troubles with Sphinx 1.4.x if major == 1 and minor > 3: @@ -470,23 +398,10 @@ if major == 1 and minor < 6: # 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', - 'Linux %s Documentation' % fn.capitalize(), - 'The kernel development community', - 'manual')) - # The name of an image file (relative to this directory) to place at the top of # the title page. #latex_logo = None @@ -513,7 +428,7 @@ for fn in os.listdir('.'): # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'thelinuxkernel', 'The Linux Kernel Documentation', + (master_doc, 'dasuboot', 'The U-Boot Documentation', [author], 1) ] @@ -527,8 +442,8 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'TheLinuxKernel', 'The Linux Kernel Documentation', - author, 'TheLinuxKernel', 'One line description of project.', + (master_doc, 'DasUBoot', 'The U-Boot Documentation', + author, 'DasUBoot', 'One line description of project.', 'Miscellaneous'), ] @@ -620,13 +535,13 @@ epub_exclude_files = ['search.html'] # 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 +# See the Sphinx chapter of http://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 = [ - ('kernel-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'), + ('uboot-documentation', u'U-Boot', u'U-Boot', u'J. Random Bozo'), ] # kernel-doc extension configuration for running Sphinx directly (e.g. by Read |