doc: update Kernel documentation build system
PATCH 1/1 doc: update Kernel documentation build system
Update the docomentation build system according to Linux v5.11-rc1.
With this patch we can build the HTML documentation using either of Sphinx 2 and Sphinx 3.
---
Except for doc/develop/logging.rst I have already sent patches for erroneous pages that did not build with Sphinx 3.
--- doc/conf.py | 141 ++++++++-- doc/sphinx/automarkup.py | 290 +++++++++++++++++++ doc/sphinx/cdomain.py | 93 +++++- doc/sphinx/kernel_abi.py | 194 +++++++++++++ doc/sphinx/kernel_feat.py | 169 +++++++++++ doc/sphinx/kerneldoc.py | 15 +- doc/sphinx/kernellog.py | 6 +- doc/sphinx/kfigure.py | 6 +- doc/sphinx/load_config.py | 27 +- doc/sphinx/maintainers_include.py | 197 +++++++++++++ doc/sphinx/parallel-wrapper.sh | 33 +++ doc/sphinx/parse-headers.pl | 6 +- doc/sphinx/requirements.txt | 5 +- scripts/kernel-doc | 450 ++++++++++++++++++++++-------- 14 files changed, 1476 insertions(+), 156 deletions(-) create mode 100644 doc/sphinx/automarkup.py create mode 100644 doc/sphinx/kernel_abi.py create mode 100644 doc/sphinx/kernel_feat.py create mode 100755 doc/sphinx/maintainers_include.py create mode 100644 doc/sphinx/parallel-wrapper.sh
doc/conf.py +113 -28
@@ -16,6 +16,8 @@ import sys import os import sphinx +from subprocess import check_output + # Get Sphinx version major, minor, patch = sphinx.version_info[:3]
@@ -31,39 +33,98 @@ 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'] +extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', + 'kfigure', 'sphinx.ext.ifconfig', 'automarkup', + 'maintainers_include', 'sphinx.ext.autosectionlabel', + 'kernel_abi', 'kernel_feat'] # -# cdomain is badly broken in Sphinx 3+. Leaving it out generates *most* -# of the docs correctly, but not all. +# 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: + 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 escaped by using c_id_attributes[] array + # Those needed to be scaped by using c_id_attributes[] array c_id_attributes = [ - - # include/linux/compiler.h + # 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') + 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):
@@ -86,9 +147,9 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = 'Das U-Boot' -copyright = 'The U-Boot development community' -author = 'The U-Boot development community' +project = 'The Linux Kernel' +copyright = 'The kernel development community' +author = 'The kernel 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
@@ -199,7 +260,7 @@ except ImportError: # 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' +#html_logo = None # 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
@@ -229,7 +290,7 @@ html_context = { # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. -#html_use_smartypants = True +html_use_smartypants = False # Custom sidebar templates, maps document names to template names. #html_sidebars = {}
@@ -279,7 +340,7 @@ html_context = { #html_search_scorer = 'scorer.js' # Output file base name for HTML help builder. -htmlhelp_basename = 'TheUBootdoc' +htmlhelp_basename = 'TheLinuxKerneldoc' # -- Options for LaTeX output ---------------------------------------------
@@ -288,7 +349,7 @@ latex_elements = { 'papersize': 'a4paper', # The font size ('10pt', '11pt' or '12pt'). -'pointsize': '8pt', +'pointsize': '11pt', # Latex figure (float) alignment #'figure_align': 'htbp',
@@ -301,13 +362,24 @@ latex_elements = { 'preamble': ''' % Use some font with UTF-8 support with XeLaTeX \\usepackage{fontspec} - \\setsansfont{DejaVu Serif} - \\setromanfont{DejaVu Sans} + \\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} + ''' + # Fix reference escape troubles with Sphinx 1.4.x if major == 1 and minor > 3: latex_elements['preamble'] += '\\renewcommand*{\\DUrole}[2]{ #2 }\n'
@@ -398,10 +470,23 @@ 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
@@ -428,7 +513,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'dasuboot', 'The U-Boot Documentation', + (master_doc, 'thelinuxkernel', 'The Linux Kernel Documentation', [author], 1) ]
@@ -442,8 +527,8 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'DasUBoot', 'The U-Boot Documentation', - author, 'DasUBoot', 'One line description of project.', + (master_doc, 'TheLinuxKernel', 'The Linux Kernel Documentation', + author, 'TheLinuxKernel', 'One line description of project.', 'Miscellaneous'), ]
@@ -535,13 +620,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 http://ralsina.me/static/manual.pdf +# 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-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'), ] # kernel-doc extension configuration for running Sphinx directly (e.g. by Read
doc/sphinx/automarkup.py new file +290 -0
290 lines not on this page · raw message
doc/sphinx/cdomain.py +92 -1
129 lines not on this page · raw message
doc/sphinx/kernel_abi.py new file +194 -0
194 lines not on this page · raw message
doc/sphinx/kernel_feat.py new file +169 -0
169 lines not on this page · raw message
doc/sphinx/kerneldoc.py +14 -1
@@ -62,6 +62,7 @@ class KernelDocDirective(Directive): 'export': directives.unchanged, 'internal': directives.unchanged, 'identifiers': directives.unchanged, + 'no-identifiers': directives.unchanged, 'functions': directives.unchanged, } has_content = False
@@ -70,6 +71,11 @@ class KernelDocDirective(Directive): env = self.state.document.settings.env cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno'] + # Pass the version string to kernel-doc, as it needs to use a different + # dialect, depending what the C domain supports for each specific + # Sphinx versions + cmd += ['-sphinx-version', sphinx.__version__] + filename = env.config.kerneldoc_srctree + '/' + self.arguments[0] export_file_patterns = []
@@ -99,6 +105,12 @@ class KernelDocDirective(Directive): else: cmd += ['-no-doc-sections'] + if 'no-identifiers' in self.options: + no_identifiers = self.options.get('no-identifiers').split() + if no_identifiers: + for i in no_identifiers: + cmd += ['-nosymbol', i] + for pattern in export_file_patterns: for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern): env.note_dependency(os.path.abspath(f))
@@ -136,7 +148,8 @@ class KernelDocDirective(Directive): lineoffset = int(match.group(1)) - 1 # we must eat our comments since the upset the markup else: - result.append(line, filename, lineoffset) + doc = env.srcdir + "/" + env.docname + ":" + str(self.lineno) + result.append(line, doc + ": " + filename, lineoffset) lineoffset += 1 node = nodes.section()
doc/sphinx/kernellog.py +5 -1
@@ -25,4 +25,8 @@ def verbose(app, message): else: app.verbose(message) - +def info(app, message): + if UseLogging: + logger.info(message) + else: + app.info(message)
doc/sphinx/kfigure.py +3 -3
@@ -29,7 +29,7 @@ u""" Used tools: - * ``dot(1)``: Graphviz (http://www.graphviz.org). If Graphviz is not + * ``dot(1)``: Graphviz (https://www.graphviz.org). If Graphviz is not available, the DOT language is inserted as literal-block. * SVG to PDF: To generate PDF, you need at least one of this tools:
@@ -41,7 +41,7 @@ u""" * generate PDF from SVG / used by PDF (LaTeX) builder * generate SVG (html-builder) and PDF (latex-builder) from DOT files. - DOT: see http://www.graphviz.org/content/dot-language + DOT: see https://www.graphviz.org/content/dot-language """
@@ -182,7 +182,7 @@ def setupTools(app): kernellog.verbose(app, "use dot(1) from: " + dot_cmd) else: kernellog.warn(app, "dot(1) not found, for better output quality install " - "graphviz from http://www.graphviz.org") + "graphviz from https://www.graphviz.org") if convert_cmd: kernellog.verbose(app, "use convert(1) from: " + convert_cmd) else:
doc/sphinx/load_config.py +26 -1
@@ -21,6 +21,29 @@ def loadConfig(namespace): and os.path.normpath(namespace["__file__"]) != os.path.normpath(config_file) ): config_file = os.path.abspath(config_file) + # Let's avoid one conf.py file just due to latex_documents + start = config_file.find('Documentation/') + if start >= 0: + start = config_file.find('/', start + 1) + + end = config_file.rfind('/') + if start >= 0 and end > 0: + dir = config_file[start + 1:end] + + print("source directory: %s" % dir) + new_latex_docs = [] + latex_documents = namespace['latex_documents'] + + for l in latex_documents: + if l[0].find(dir + '/') == 0: + has = True + fn = l[0][len(dir) + 1:] + new_latex_docs.append((fn, l[1], l[2], l[3], l[4])) + break + + namespace['latex_documents'] = new_latex_docs + + # If there is an extra conf.py file, load it if os.path.isfile(config_file): sys.stdout.write("load additional sphinx-config: %s\n" % config_file) config = namespace.copy()
@@ -29,4 +52,6 @@ def loadConfig(namespace): del config['__file__'] namespace.update(config) else: - sys.stderr.write("WARNING: additional sphinx-config not found: %s\n" % config_file) + config = namespace.copy() + config['tags'].add("subproject") + namespace.update(config)
doc/sphinx/maintainers_include.py new file +197 -0
197 lines not on this page · raw message
doc/sphinx/parallel-wrapper.sh new file +33 -0
@@ -0,0 +1,33 @@ +#!/bin/sh +# SPDX-License-Identifier: GPL-2.0+ +# +# Figure out if we should follow a specific parallelism from the make +# environment (as exported by scripts/jobserver-exec), or fall back to +# the "auto" parallelism when "-jN" is not specified at the top-level +# "make" invocation. + +sphinx="$1" +shift || true + +parallel="$PARALLELISM" +if [ -z "$parallel" ] ; then + # If no parallelism is specified at the top-level make, then + # fall back to the expected "-jauto" mode that the "htmldocs" + # target has had. + auto=$(perl -e 'open IN,"'"$sphinx"' --version 2>&1 |"; + while (<IN>) { + if (m/([\d\.]+)/) { + print "auto" if ($1 >= "1.7") + } + } + close IN') + if [ -n "$auto" ] ; then + parallel="$auto" + fi +fi +# Only if some parallelism has been determined do we add the -jN option. +if [ -n "$parallel" ] ; then + parallel="-j$parallel" +fi + +exec "$sphinx" $parallel "$@"
doc/sphinx/parse-headers.pl +3 -3
@@ -1,4 +1,4 @@ -#!/usr/bin/perl +#!/usr/bin/env perl use strict; use Text::Tabs; use Getopt::Long;
@@ -110,7 +110,7 @@ while (<IN>) { ) { my $s = $1; - $structs{$s} = "struct :c:type:`$s`\\ "; + $structs{$s} = "struct $s\\ "; next; } }
@@ -393,7 +393,7 @@ Report bugs to Mauro Carvalho Chehab <[email protected]> Copyright (c) 2016 by Mauro Carvalho Chehab <[email protected]>. -License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>. +License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.
doc/sphinx/requirements.txt +3 -2
@@ -1,3 +1,4 @@ -docutils==0.12 -Sphinx==1.4.9 +docutils +Sphinx==2.4.4 sphinx_rtd_theme +six
scripts/kernel-doc +334 -116
836 lines not on this page · raw message
--
2.29.2
PATCH 1/1 doc: update Kernel documentation build system
Quoted 23 lines · Heinrich Schuchardt
Update the docomentation build system according to Linux v5.11-rc1.
With this patch we can build the HTML documentation using either of Sphinx 2 and Sphinx 3.
Signed-off-by Heinrich Schuchardt <[email protected]>---
Except fordoc/develop/logging.rstI have already sent patches for erroneous pages that did not build with Sphinx 3.--- doc/conf.py | 141 ++++++++-- doc/sphinx/automarkup.py | 290 +++++++++++++++++++ doc/sphinx/cdomain.py | 93 +++++- doc/sphinx/kernel_abi.py | 194 +++++++++++++ doc/sphinx/kernel_feat.py | 169 +++++++++++ doc/sphinx/kerneldoc.py | 15 +- doc/sphinx/kernellog.py | 6 +- doc/sphinx/kfigure.py | 6 +- doc/sphinx/load_config.py | 27 +- doc/sphinx/maintainers_include.py | 197 +++++++++++++ doc/sphinx/parallel-wrapper.sh | 33 +++ doc/sphinx/parse-headers.pl | 6 +-
Quoted 8 lines
doc/sphinx/requirements.txt | 5 +- scripts/kernel-doc | 450 ++++++++++++++++++++++-------- 14 files changed, 1476 insertions(+), 156 deletions(-) create mode 100644 doc/sphinx/automarkup.py create mode 100644 doc/sphinx/kernel_abi.py create mode 100644 doc/sphinx/kernel_feat.py create mode 100755 doc/sphinx/maintainers_include.py create mode 100644 doc/sphinx/parallel-wrapper.sh
PATCH 1/1 doc: update Kernel documentation build system
In reply to Heinrich SchuchardtQuoted 7 lines · Heinrich Schuchardt
Update the docomentation build system according to Linux v5.11-rc1.
With this patch we can build the HTML documentation using either of Sphinx 2 and Sphinx 3.
Signed-off-by Heinrich Schuchardt <[email protected]>Reviewed-by Simon Glass <[email protected]>
Applied to u-boot/master, thanks!
Signature · 8 lines
Tom -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 659 bytes Desc: not available URL: <https://lists.denx.de/pipermail/u-boot/attachments/20210123/02aeeecd/attachment.sig>
PATCH 1/1 doc: update Kernel documentation build system
Quoted 11 lines · Tom Rini
Quoted 7 lines · Heinrich Schuchardt
Update the docomentation build system according to Linux v5.11-rc1.
With this patch we can build the HTML documentation using either of Sphinx 2 and Sphinx 3.
Signed-off-by Heinrich Schuchardt <[email protected]>Reviewed-by Simon Glass <[email protected]>Applied to u-boot/master, thanks!
I've had to revert this. While I caught and fixed up in a semi-logical way one duplicate label problem, there's another now that I see, and probably many more once I rework that one. It's unclear as well how best to handle these otherwise logical duplicate labels, such as "eMMC" in doc/board/microchip/mpfs_icicle.rst for example.
Signature · 8 lines
Tom -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 659 bytes Desc: not available URL: <https://lists.denx.de/pipermail/u-boot/attachments/20210123/17fc8e39/attachment.sig>
PATCH 1/1 doc: update Kernel documentation build system
Quoted 11 lines · Tom Rini
Quoted 10 lines · Tom Rini
Quoted 7 lines · Heinrich Schuchardt
Update the docomentation build system according to Linux v5.11-rc1.
With this patch we can build the HTML documentation using either of Sphinx 2 and Sphinx 3.
Signed-off-by Heinrich Schuchardt <[email protected]>Reviewed-by Simon Glass <[email protected]>
Quoted 7 lines
Quoted 1 line
Applied to u-boot/master, thanks!
I've had to revert this. While I caught and fixed up in a semi-logical way one duplicate label problem, there's another now that I see, and probably many more once I rework that one. It's unclear as well how best to handle these otherwise logical duplicate labels, such as "eMMC" in
doc/board/microchip/mpfs_icicle.rstfor example.
Sphinx 2 is not available for current Linux distributions. Without this patch we cannot build with Sphinx 3.
All pages must be deduplicated. Instead of duplicate information references have to be used.
Once that is done and the patch is reapplied we must make sure that on gitlab we use Sphinx 3 by moving to a current Ubuntu version.
Best regards
Heinrich
PATCH 1/1 doc: update Kernel documentation build system
Quoted 14 lines · Heinrich Schuchardt
Quoted 13 lines · Tom Rini
Quoted 11 lines · Tom Rini
Quoted 7 lines · Heinrich Schuchardt
Update the docomentation build system according to Linux v5.11-rc1.
With this patch we can build the HTML documentation using either of Sphinx 2 and Sphinx 3.
Signed-off-by Heinrich Schuchardt <[email protected]>Reviewed-by Simon Glass <[email protected]>Applied to u-boot/master, thanks!
Quoted 8 lines
Quoted 5 lines
I've had to revert this. While I caught and fixed up in a semi-logical way one duplicate label problem, there's another now that I see, and probably many more once I rework that one. It's unclear as well how best to handle these otherwise logical duplicate labels, such as "eMMC" in
doc/board/microchip/mpfs_icicle.rstfor example.Sphinx 2 is not available for current Linux distributions. Without this patch we cannot build with Sphinx 3.
We need to be careful when saying "current". Ubuntu 18.04 is still quite current enough and will be until 2022 (as it doesn't go EOL until 2023). I'm not sure I can even get Sphinx 3.
Quoted 2 lines
All pages must be deduplicated. Instead of duplicate information references have to be used.
So long as it can be done in a way where documentation reads well still, yes. For example, how should we re-write the example I mentioned so that "eMMC" isn't duplicated?
Quoted 2 lines
Once that is done and the patch is reapplied we must make sure that on gitlab we use Sphinx 3 by moving to a current Ubuntu version.
We'll have to figure out what to do about updating CI, but I'm not sure moving the host version is a good idea at this time.
Signature · 8 lines
Tom -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 659 bytes Desc: not available URL: <https://lists.denx.de/pipermail/u-boot/attachments/20210124/7f6077c2/attachment.sig>
PATCH 1/1 doc: update Kernel documentation build system
Quoted 21 lines · Tom Rini
Quoted 20 lines · Heinrich Schuchardt
Quoted 18 lines · Tom Rini
Quoted 11 lines · Tom Rini
Quoted 7 lines · Heinrich Schuchardt
Update the docomentation build system according to Linux v5.11-rc1.
With this patch we can build the HTML documentation using either of Sphinx 2 and Sphinx 3.
Signed-off-by Heinrich Schuchardt <[email protected]>Reviewed-by Simon Glass <[email protected]>Applied to u-boot/master, thanks!
I've had to revert this. While I caught and fixed up in a semi-logical way one duplicate label problem, there's another now that I see, and probably many more once I rework that one. It's unclear as well how best to handle these otherwise logical duplicate labels, such as "eMMC" in
doc/board/microchip/mpfs_icicle.rstfor example.
Quoted 6 lines
Quoted 2 lines
Sphinx 2 is not available for current Linux distributions. Without this patch we cannot build with Sphinx 3.
We need to be careful when saying "current". Ubuntu 18.04 is still quite current enough and will be until 2022 (as it doesn't go EOL until 2023). I'm not sure I can even get Sphinx 3.
Developers will not be able to test the documentation if 'make htmldocs' fails on their machines because their distribution does not provide Sphinx 2.
The current Ubuntu release is 20.10 and provides Sphinx 3.2.
https://packages.ubuntu.com/groovy/sphinx-common.
Arch Linux is on Sphinx 3.4.
https://archlinux.org/packages/community/any/python-sphinx/
Best regards
Heinrich
Quoted 14 lines
Quoted 3 lines
All pages must be deduplicated. Instead of duplicate information references have to be used.
So long as it can be done in a way where documentation reads well still, yes. For example, how should we re-write the example I mentioned so that "eMMC" isn't duplicated?
Quoted 2 lines
Once that is done and the patch is reapplied we must make sure that on gitlab we use Sphinx 3 by moving to a current Ubuntu version.
We'll have to figure out what to do about updating CI, but I'm not sure moving the host version is a good idea at this time.
PATCH 1/1 doc: update Kernel documentation build system
Quoted 33 lines · Heinrich Schuchardt
Quoted 21 lines · Tom Rini
Quoted 20 lines · Heinrich Schuchardt
Quoted 18 lines · Tom Rini
Quoted 11 lines · Tom Rini
Quoted 7 lines · Heinrich Schuchardt
Update the docomentation build system according to Linux v5.11-rc1.
With this patch we can build the HTML documentation using either of Sphinx 2 and Sphinx 3.
Signed-off-by Heinrich Schuchardt <[email protected]>Reviewed-by Simon Glass <[email protected]>Applied to u-boot/master, thanks!
I've had to revert this. While I caught and fixed up in a semi-logical way one duplicate label problem, there's another now that I see, and probably many more once I rework that one. It's unclear as well how best to handle these otherwise logical duplicate labels, such as "eMMC" in
doc/board/microchip/mpfs_icicle.rstfor example.Quoted 6 lines
Quoted 2 lines
Sphinx 2 is not available for current Linux distributions. Without this patch we cannot build with Sphinx 3.
We need to be careful when saying "current". Ubuntu 18.04 is still quite current enough and will be until 2022 (as it doesn't go EOL until 2023). I'm not sure I can even get Sphinx 3.
Developers will not be able to test the documentation if 'make htmldocs' fails on their machines because their distribution does not provide Sphinx 2.
Quoted 5 lines
The current Ubuntu release is 20.10 and provides Sphinx 3.2.
https://packages.ubuntu.com/groovy/sphinx-common.Arch Linux is on Sphinx 3.4.
https://archlinux.org/packages/community/any/python-sphinx/
I use Arch Linux. To compile documentation, I use a virtualenv with Sphinx 2. However, I would like to be able to use the Sphinx included with my distribution. It also took some searching to determine that I needed Sphinx 2 (as I had previously compiled documentation without issue).
--Sean
Quoted 20 lines
Best regards
Heinrich
Quoted 14 lines
Quoted 3 lines
All pages must be deduplicated. Instead of duplicate information references have to be used.
So long as it can be done in a way where documentation reads well still, yes. For example, how should we re-write the example I mentioned so that "eMMC" isn't duplicated?
Quoted 2 lines
Once that is done and the patch is reapplied we must make sure that on gitlab we use Sphinx 3 by moving to a current Ubuntu version.
We'll have to figure out what to do about updating CI, but I'm not sure moving the host version is a good idea at this time.
PATCH 1/1 doc: update Kernel documentation build system
In reply to Heinrich SchuchardtQuoted 33 lines · Heinrich Schuchardt
Quoted 21 lines · Tom Rini
Quoted 20 lines · Heinrich Schuchardt
Quoted 18 lines · Tom Rini
Quoted 11 lines · Tom Rini
Quoted 7 lines · Heinrich Schuchardt
Update the docomentation build system according to Linux v5.11-rc1.
With this patch we can build the HTML documentation using either of Sphinx 2 and Sphinx 3.
Signed-off-by Heinrich Schuchardt <[email protected]>Reviewed-by Simon Glass <[email protected]>Applied to u-boot/master, thanks!
I've had to revert this. While I caught and fixed up in a semi-logical way one duplicate label problem, there's another now that I see, and probably many more once I rework that one. It's unclear as well how best to handle these otherwise logical duplicate labels, such as "eMMC" in
doc/board/microchip/mpfs_icicle.rstfor example.Quoted 6 lines
Quoted 2 lines
Sphinx 2 is not available for current Linux distributions. Without this patch we cannot build with Sphinx 3.
We need to be careful when saying "current". Ubuntu 18.04 is still quite current enough and will be until 2022 (as it doesn't go EOL until 2023). I'm not sure I can even get Sphinx 3.
Developers will not be able to test the documentation if 'make htmldocs' fails on their machines because their distribution does not provide Sphinx 2.
Quoted 5 lines
The current Ubuntu release is 20.10 and provides Sphinx 3.2.
https://packages.ubuntu.com/groovy/sphinx-common.Arch Linux is on Sphinx 3.4.
https://archlinux.org/packages/community/any/python-sphinx/
And 18.04 is an LTS that doesn't go EOL until April 2023. Developers will not be test their documentation if they don't have Sphinx 3 available. Either side can do as Sean notes and use venv to provide whatever, and we need to make the error in that case much clearer. I would assume that the "still works with gcc-4.9!" Linux kernel has a bit clearer of an error out in that case. If not perhaps they would take a patch :)
But much more importantly:
Quoted 6 lines
Quoted 6 lines
Quoted 2 lines
All pages must be deduplicated. Instead of duplicate information references have to be used.
So long as it can be done in a way where documentation reads well still, yes. For example, how should we re-write the example I mentioned so that "eMMC" isn't duplicated?
Is what really needs to be solved. Show me how the document in question gets updated to read well and not have the duplicated heading message.
Signature · 8 lines
Tom -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 659 bytes Desc: not available URL: <https://lists.denx.de/pipermail/u-boot/attachments/20210124/966d3da6/attachment.sig>
PATCH 1/1 doc: update Kernel documentation build system
Hi,
Quoted 53 lines · Tom Rini
Quoted 33 lines · Heinrich Schuchardt
Quoted 21 lines · Tom Rini
Quoted 20 lines · Heinrich Schuchardt
Quoted 18 lines · Tom Rini
Quoted 11 lines · Tom Rini
Quoted 7 lines · Heinrich Schuchardt
Update the docomentation build system according to Linux v5.11-rc1.
With this patch we can build the HTML documentation using either of Sphinx 2 and Sphinx 3.
Signed-off-by Heinrich Schuchardt <[email protected]>Reviewed-by Simon Glass <[email protected]>Applied to u-boot/master, thanks!
I've had to revert this. While I caught and fixed up in a semi-logical way one duplicate label problem, there's another now that I see, and probably many more once I rework that one. It's unclear as well how best to handle these otherwise logical duplicate labels, such as "eMMC" in
doc/board/microchip/mpfs_icicle.rstfor example.Quoted 6 lines
Quoted 2 lines
Sphinx 2 is not available for current Linux distributions. Without this patch we cannot build with Sphinx 3.
We need to be careful when saying "current". Ubuntu 18.04 is still quite current enough and will be until 2022 (as it doesn't go EOL until 2023). I'm not sure I can even get Sphinx 3.
Developers will not be able to test the documentation if 'make htmldocs' fails on their machines because their distribution does not provide Sphinx 2.
Quoted 5 lines
The current Ubuntu release is 20.10 and provides Sphinx 3.2.
https://packages.ubuntu.com/groovy/sphinx-common.Arch Linux is on Sphinx 3.4.
https://archlinux.org/packages/community/any/python-sphinx/And 18.04 is an LTS that doesn't go EOL until April 2023. Developers will not be test their documentation if they don't have Sphinx 3 available. Either side can do as Sean notes and use venv to provide whatever, and we need to make the error in that case much clearer. I would assume that the "still works with gcc-4.9!" Linux kernel has a bit clearer of an error out in that case. If not perhaps they would take a patch :)
But much more importantly:
Quoted 3 lines
Quoted 3 lines
Quoted 2 lines
All pages must be deduplicated. Instead of duplicate information references have to be used.
Quoted 6 lines
Quoted 3 lines
Quoted 3 lines
So long as it can be done in a way where documentation reads well still, yes. For example, how should we re-write the example I mentioned so that "eMMC" isn't duplicated?
Is what really needs to be solved. Show me how the document in question gets updated to read well and not have the duplicated heading message.
I agree we have to support Sphinx 2 for a while. So we need both!
Minor niggle - is it possible to fix the need for the -w flag? Can the Makefile check the version and pass the correct flags itself?
Regards,
Simon
PATCH 1/1 doc: update Kernel documentation build system
Quoted 60 lines · Simon Glass
Hi,
Quoted 57 lines · Tom Rini
Quoted 33 lines · Heinrich Schuchardt
Quoted 21 lines · Tom Rini
Quoted 20 lines · Heinrich Schuchardt
Quoted 18 lines · Tom Rini
Quoted 11 lines · Tom Rini
Quoted 7 lines · Heinrich Schuchardt
Update the docomentation build system according to Linux v5.11-rc1.
With this patch we can build the HTML documentation using either of Sphinx 2 and Sphinx 3.
Signed-off-by Heinrich Schuchardt <[email protected]>Reviewed-by Simon Glass <[email protected]>Applied to u-boot/master, thanks!
I've had to revert this. While I caught and fixed up in a semi-logical way one duplicate label problem, there's another now that I see, and probably many more once I rework that one. It's unclear as well how best to handle these otherwise logical duplicate labels, such as "eMMC" in
doc/board/microchip/mpfs_icicle.rstfor example.Quoted 6 lines
Quoted 2 lines
Sphinx 2 is not available for current Linux distributions. Without this patch we cannot build with Sphinx 3.
We need to be careful when saying "current". Ubuntu 18.04 is still quite current enough and will be until 2022 (as it doesn't go EOL until 2023). I'm not sure I can even get Sphinx 3.
Developers will not be able to test the documentation if 'make htmldocs' fails on their machines because their distribution does not provide Sphinx 2.
Quoted 5 lines
The current Ubuntu release is 20.10 and provides Sphinx 3.2.
https://packages.ubuntu.com/groovy/sphinx-common.Arch Linux is on Sphinx 3.4.
https://archlinux.org/packages/community/any/python-sphinx/And 18.04 is an LTS that doesn't go EOL until April 2023. Developers will not be test their documentation if they don't have Sphinx 3 available. Either side can do as Sean notes and use venv to provide whatever, and we need to make the error in that case much clearer. I would assume that the "still works with gcc-4.9!" Linux kernel has a bit clearer of an error out in that case. If not perhaps they would take a patch :)
But much more importantly:
Quoted 6 lines
Quoted 6 lines
Quoted 2 lines
All pages must be deduplicated. Instead of duplicate information references have to be used.
So long as it can be done in a way where documentation reads well still, yes. For example, how should we re-write the example I mentioned so that "eMMC" isn't duplicated?
Quoted 7 lines
Quoted 2 lines
Is what really needs to be solved. Show me how the document in question gets updated to read well and not have the duplicated heading message.
I agree we have to support Sphinx 2 for a while. So we need both!
Minor niggle - is it possible to fix the need for the -w flag? Can the
Makefilecheck the version and pass the correct flags itself?
Do you mean "-W Turn warnings into errors" which never changed its meaning in Sphinx since version 1.0?
Yes, we want to this flag to reject any patch with broken reStructered text.
Best regards
Heinrich
PATCH 1/1 doc: update Kernel documentation build system
Quoted 66 lines · Heinrich Schuchardt
Quoted 65 lines · Simon Glass
Hi,
Quoted 53 lines · Tom Rini
Quoted 33 lines · Heinrich Schuchardt
Quoted 21 lines · Tom Rini
Quoted 20 lines · Heinrich Schuchardt
Quoted 18 lines · Tom Rini
Quoted 11 lines · Tom Rini
Quoted 7 lines · Heinrich Schuchardt
Update the docomentation build system according to Linux v5.11-rc1.
With this patch we can build the HTML documentation using either of Sphinx 2 and Sphinx 3.
Signed-off-by Heinrich Schuchardt <[email protected]>Reviewed-by Simon Glass <[email protected]>Applied to u-boot/master, thanks!
I've had to revert this. While I caught and fixed up in a semi-logical way one duplicate label problem, there's another now that I see, and probably many more once I rework that one. It's unclear as well how best to handle these otherwise logical duplicate labels, such as "eMMC" in
doc/board/microchip/mpfs_icicle.rstfor example.Quoted 6 lines
Quoted 2 lines
Sphinx 2 is not available for current Linux distributions. Without this patch we cannot build with Sphinx 3.
We need to be careful when saying "current". Ubuntu 18.04 is still quite current enough and will be until 2022 (as it doesn't go EOL until 2023). I'm not sure I can even get Sphinx 3.
Developers will not be able to test the documentation if 'make htmldocs' fails on their machines because their distribution does not provide Sphinx 2.
Quoted 5 lines
The current Ubuntu release is 20.10 and provides Sphinx 3.2.
https://packages.ubuntu.com/groovy/sphinx-common.Arch Linux is on Sphinx 3.4.
https://archlinux.org/packages/community/any/python-sphinx/And 18.04 is an LTS that doesn't go EOL until April 2023. Developers will not be test their documentation if they don't have Sphinx 3 available. Either side can do as Sean notes and use venv to provide whatever, and we need to make the error in that case much clearer. I would assume that the "still works with gcc-4.9!" Linux kernel has a bit clearer of an error out in that case. If not perhaps they would take a patch :)
But much more importantly:
Quoted 3 lines
Quoted 3 lines
Quoted 2 lines
All pages must be deduplicated. Instead of duplicate information references have to be used.
Quoted 6 lines
Quoted 3 lines
Quoted 3 lines
So long as it can be done in a way where documentation reads well still, yes. For example, how should we re-write the example I mentioned so that "eMMC" isn't duplicated?
Is what really needs to be solved. Show me how the document in question gets updated to read well and not have the duplicated heading message.
I agree we have to support Sphinx 2 for a while. So we need both!
Quoted 7 lines
Quoted 2 lines
Minor niggle - is it possible to fix the need for the -w flag? Can the
Makefilecheck the version and pass the correct flags itself?Do you mean "-W Turn warnings into errors" which never changed its meaning in Sphinx since version 1.0?
Yes, we want to this flag to reject any patch with broken reStructered text.
So it is not like dtc/gcc/etc where we can do -Wno-some-specific-check, OK.
Signature · 8 lines
Tom -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 659 bytes Desc: not available URL: <https://lists.denx.de/pipermail/u-boot/attachments/20210126/3b30a43b/attachment.sig>
PATCH 1/1 doc: update Kernel documentation build system
Hi Heinrich,
Quoted 71 lines · Tom Rini
Quoted 69 lines · Heinrich Schuchardt
Quoted 67 lines · Simon Glass
Hi,
Quoted 53 lines · Tom Rini
Quoted 33 lines · Heinrich Schuchardt
Quoted 21 lines · Tom Rini
Quoted 20 lines · Heinrich Schuchardt
Quoted 18 lines · Tom Rini
Quoted 11 lines · Tom Rini
Quoted 7 lines · Heinrich Schuchardt
Update the docomentation build system according to Linux v5.11-rc1.
With this patch we can build the HTML documentation using either of Sphinx 2 and Sphinx 3.
Signed-off-by Heinrich Schuchardt <[email protected]>Reviewed-by Simon Glass <[email protected]>Applied to u-boot/master, thanks!
I've had to revert this. While I caught and fixed up in a semi-logical way one duplicate label problem, there's another now that I see, and probably many more once I rework that one. It's unclear as well how best to handle these otherwise logical duplicate labels, such as "eMMC" in
doc/board/microchip/mpfs_icicle.rstfor example.Quoted 6 lines
Quoted 2 lines
Sphinx 2 is not available for current Linux distributions. Without this patch we cannot build with Sphinx 3.
We need to be careful when saying "current". Ubuntu 18.04 is still quite current enough and will be until 2022 (as it doesn't go EOL until 2023). I'm not sure I can even get Sphinx 3.
Developers will not be able to test the documentation if 'make htmldocs' fails on their machines because their distribution does not provide Sphinx 2.
Quoted 5 lines
The current Ubuntu release is 20.10 and provides Sphinx 3.2.
https://packages.ubuntu.com/groovy/sphinx-common.Arch Linux is on Sphinx 3.4.
https://archlinux.org/packages/community/any/python-sphinx/And 18.04 is an LTS that doesn't go EOL until April 2023. Developers will not be test their documentation if they don't have Sphinx 3 available. Either side can do as Sean notes and use venv to provide whatever, and we need to make the error in that case much clearer. I would assume that the "still works with gcc-4.9!" Linux kernel has a bit clearer of an error out in that case. If not perhaps they would take a patch :)
But much more importantly:
Quoted 3 lines
Quoted 3 lines
Quoted 2 lines
All pages must be deduplicated. Instead of duplicate information references have to be used.
Quoted 6 lines
Quoted 3 lines
Quoted 3 lines
So long as it can be done in a way where documentation reads well still, yes. For example, how should we re-write the example I mentioned so that "eMMC" isn't duplicated?
Is what really needs to be solved. Show me how the document in question gets updated to read well and not have the duplicated heading message.
I agree we have to support Sphinx 2 for a while. So we need both!
Minor niggle - is it possible to fix the need for the -w flag? Can the
Makefilecheck the version and pass the correct flags itself?
Quoted 8 lines
Quoted 4 lines
Do you mean "-W Turn warnings into errors" which never changed its meaning in Sphinx since version 1.0?
Yes, we want to this flag to reject any patch with broken reStructered text.
So it is not like dtc/gcc/etc where we can do -Wno-some-specific-check, OK.
Really what I am looking for is being able to build with version 2 or 3 without any problems, rather than requiring v3, or requiring removing -w . Is that what we will end up with?
Regards,
Simon