Commit bec7550c authored by Linus Torvalds's avatar Linus Torvalds
Browse files

Merge tag 'docs-5.2-fixes2' of git://git.lwn.net/linux 

Pull documentation fixes from Jonathan Corbet:
 "The Sphinx 2.0 release contained a few incompatible API changes that
  broke our extensions and, thus, the documentation build in general.
  Who knew that those deprecation warnings it was outputting actually
  meant we should change something? This set of fixes makes the build
  work again with Sphinx 2.0 and eliminates the warnings for 1.8. As
  part of that, we also need a few fixes to the docs for places where
  the new Sphinx is more strict.

  It is a bit late in the cycle for this kind of change, but it does fix
  problems that people are experiencing now.

  There has been some talk of raising the minimum version of Sphinx we
  support. I don't want to do that abruptly, though, so these changes
  add some glue to continue to support versions back to 1.3. We will be
  adding some infrastructure soon to nudge users of old versions
  forward, with the idea of maybe increasing our minimum version (and
  removing this glue) sometime in the future"

* tag 'docs-5.2-fixes2' of git://git.lwn.net/linux:
  drm/i915: Maintain consistent documentation subsection ordering
  scripts/sphinx-pre-install: make it handle Sphinx versions
  docs: Fix conf.py for Sphinx 2.0
  docs: fix multiple doc build warnings in enumeration.rst
  lib/list_sort: fix kerneldoc build error
  docs: fix numaperf.rst and add it to the doc tree
  doc: Cope with the deprecation of AutoReporter
  doc: Cope with Sphinx logging deprecations
parents 2b28601d 551bd336

Documentation/admin-guide/mm/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -31,6 +31,7 @@ the Linux memory management. 
   ksm

   memory-hotplug

   numa_memory_policy

   numaperf

   pagemap

   soft-dirty

   transhuge

Documentation/admin-guide/mm/numaperf.rst

+1 −1
Original line number Diff line number Diff line
@@ -15,7 +15,7 @@ characteristics. Some memory may share the same node as a CPU, and others 
are provided as memory only nodes. While memory only nodes do not provide

CPUs, they may still be local to one or more compute nodes relative to

other nodes. The following diagram shows one such example of two compute

nodes with local memory and a memory only node for each of compute node:

nodes with local memory and a memory only node for each of compute node::



 +------------------+     +------------------+

 | Compute Node 0   +-----+ Compute Node 1   |

Documentation/conf.py

+1 −1
Original line number Diff line number Diff line
@@ -37,7 +37,7 @@ needs_sphinx = '1.3' 
extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure', 'sphinx.ext.ifconfig']



# The name of the math extension changed on Sphinx 1.4

if major == 1 and minor > 3:

if (major == 1 and minor > 3) or (major > 1):

    extensions.append("sphinx.ext.imgmath")

else:

    extensions.append("sphinx.ext.pngmath")

Documentation/firmware-guide/acpi/enumeration.rst

+1 −1
Original line number Diff line number Diff line
@@ -423,7 +423,7 @@ will be enumerated to depends on the device ID returned by _HID. 


For example, the following ACPI sample might be used to enumerate an lm75-type

I2C temperature sensor and match it to the driver using the Device Tree

namespace link:

namespace link::



	Device (TMP0)

	{

Documentation/sphinx/kerneldoc.py

+33 −11
Original line number Diff line number Diff line
@@ -37,8 +37,20 @@ import glob 
from docutils import nodes, statemachine

from docutils.statemachine import ViewList

from docutils.parsers.rst import directives, Directive



#

# AutodocReporter is only good up to Sphinx 1.7

#

import sphinx



Use_SSI = sphinx.__version__[:3] >= '1.7'

if Use_SSI:

    from sphinx.util.docutils import switch_source_input

else:

    from sphinx.ext.autodoc import AutodocReporter



import kernellog



__version__  = '1.0'



class KernelDocDirective(Directive):
@@ -90,7 +102,8 @@ class KernelDocDirective(Directive): 
        cmd += [filename]



        try:

            env.app.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd)))

            kernellog.verbose(env.app,

                              'calling kernel-doc \'%s\'' % (" ".join(cmd)))



            p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)

            out, err = p.communicate()
@@ -100,7 +113,8 @@ class KernelDocDirective(Directive): 
            if p.returncode != 0:

                sys.stderr.write(err)



                env.app.warn('kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode))

                kernellog.warn(env.app,

                               'kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode))

                return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]

            elif env.config.kerneldoc_verbosity > 0:

                sys.stderr.write(err)
@@ -121,21 +135,29 @@ class KernelDocDirective(Directive): 
                    lineoffset += 1



            node = nodes.section()

            buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter

            self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter)

            self.state.memo.title_styles, self.state.memo.section_level = [], 0

            try:

                self.state.nested_parse(result, 0, node, match_titles=1)

            finally:

                self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf

            self.do_parse(result, node)



            return node.children



        except Exception as e:  # pylint: disable=W0703

            env.app.warn('kernel-doc \'%s\' processing failed with: %s' %

            kernellog.warn(env.app, 'kernel-doc \'%s\' processing failed with: %s' %

                           (" ".join(cmd), str(e)))

            return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]



    def do_parse(self, result, node):

        if Use_SSI:

            with switch_source_input(self.state, result):

                self.state.nested_parse(result, 0, node, match_titles=1)

        else:

            save = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter

            self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter)

            self.state.memo.title_styles, self.state.memo.section_level = [], 0

            try:

                self.state.nested_parse(result, 0, node, match_titles=1)

            finally:

                self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = save





def setup(app):

    app.add_config_value('kerneldoc_bin', None, 'env')

    app.add_config_value('kerneldoc_srctree', None, 'env')

CRA Git | Maintained and supported by SUSTech CRA and CCSE