Merge branch 'mauro' into docs-mw

Mauro's work to include documentation from our Python modules.  His cover
letter follows:

This is an extended version of:
    https://lore.kernel.org/linux-doc/cover.1768488832.git.mchehab+huawei@kernel.org/

It basically adds everything we currently have inside libs/tool/python
to "tools" book inside documentation.

This version should be independent of the other series yet to be merged,
(including the jobserver one).

The vast amount of changes here are docstring cleanups and additions.
They mainly consists on:

- ensuring that every phrase will end with a period, making it uniform
  along all files;
- cleaning ups to better uniform docstrings;
- variable descriptions now use "#:" markup, as it allows autodoc to
  add them inside the documentation;
- added some missing docstrings;
- some new blank lines at comments to make ReST syntax parser happy;
- add a couple of sphinx markups (mainly, code blocks).

Most of those are minor changes, affecting only comments.

It also has one patch per libarary type, adding them to docs.

For kernel-doc, I did the cleanups first, as there is one code block
inside tools/lib/python/kdoc/latex_fonts.py that would cause a Sphinx
crash without such markups.

The series actually starts with 3 fixes:

- avoid "*" markups on indexes with deep> 3 to override text
- a variable rename to stop abusing doctree name
- don't rely on cwd to get Documentation/ location

patch 4 adds support to document scripts either at:
    - tools/
    - scripts/

patch 5 contains a CSS to better display autodoc html output.

For those who want to play with documentation, documenting a python
file is very simple. All it takes is to use:

    .. automodule:: lib.python.<dir+name>

Usually, we add a couple of control members to it to adjust
the desired documentation scope (add/remove members, showing class
inheritance, showing members that currently don't have
docstrings, etc). That's why we're using:

    .. automodule:: lib.python.kdoc.enrich_formatter
       :members:
       :show-inheritance:
       :undoc-members:

(and similar) inside tools/kdoc*.rst.

autodoc allows filtering in/out members, file docstrings, etc.

It also allows documenting just some members or functions with
directives like:

    ..autofunction:
    ..automember:

Sphinx also has a helper script to generate .rst files with
documentation:

    $ sphinx-apidoc -o foobar tools/lib/python/

which can be helpful to discover what should be documented,
although changes are needed to use what it produces.

diff --cc Documentation/conf.py
Simple merge

diff --cc tools/lib/python/jobserver.py
index a7c70ff4c375f9452e3f3a9546aa9ac729154a10,8da1973e5c87a8b20f0f4666c9e5e5f056fce9c0..aba22c33393d300ffb1cbcc1f148ec1fa42aba1d
--- 1/tools/lib/python/jobserver.py
--- 2/tools/lib/python/jobserver.py
+++ b/tools/lib/python/jobserver.py
@@@ -61,101 -62,67 +65,101 @@@ class JobserverExec
  
          if self.is_open:
              return
 -
 -        try:
 -            # Fetch the make environment options.
 -            flags = os.environ["MAKEFLAGS"]
 -            # Look for "--jobserver=R,W"
 -            # Note that GNU Make has used --jobserver-fds and --jobserver-auth
 -            # so this handles all of them.
 -            opts = [x for x in flags.split(" ") if x.startswith("--jobserver")]
 -
 -            # Parse out R,W file descriptor numbers and set them nonblocking.
 -            # If the MAKEFLAGS variable contains multiple instances of the
 -            # --jobserver-auth= option, the last one is relevant.
 -            fds = opts[-1].split("=", 1)[1]
 -
 -            # Starting with GNU Make 4.4, named pipes are used for reader
 -            # and writer.
 -            # Example argument: --jobserver-auth=fifo:/tmp/GMfifo8134
 -            _, _, path = fds.partition("fifo:")
 -
 -            if path:
 +        self.is_open = True  # We only try once
 +        self.claim = None
 +        #
 +        # Check the make flags for "--jobserver=R,W"
 +        # Note that GNU Make has used --jobserver-fds and --jobserver-auth
 +        # so this handles all of them.
 +        #
 +        flags = os.environ.get('MAKEFLAGS', '')
 +        opts = [x for x in flags.split(" ") if x.startswith("--jobserver")]
 +        if not opts:
 +            return
 +        #
 +        # Separate out the provided file descriptors
 +        #
 +        split_opt = opts[-1].split('=', 1)
 +        if len(split_opt) != 2:
 +            warn('unparseable option:', opts[-1])
 +            return
 +        fds = split_opt[1]
 +        #
 +        # As of GNU Make 4.4, we'll be looking for a named pipe
 +        # identified as fifo:path
 +        #
 +        if fds.startswith('fifo:'):
 +            path = fds[len('fifo:'):]
 +            try:
                  self.reader = os.open(path, os.O_RDONLY | os.O_NONBLOCK)
                  self.writer = os.open(path, os.O_WRONLY)
 -            else:
 -                self.reader, self.writer = [int(x) for x in fds.split(",", 1)]
 +            except (OSError, IOError):
 +                warn('unable to open jobserver pipe', path)
 +                return
 +        #
 +        # Otherwise look for integer file-descriptor numbers.
 +        #
 +        else:
 +            split_fds = fds.split(',')
 +            if len(split_fds) != 2:
 +                warn('malformed jobserver file descriptors:', fds)
 +                return
 +            try:
 +                self.reader = int(split_fds[0])
 +                self.writer = int(split_fds[1])
 +            except ValueError:
 +                warn('non-integer jobserver file-descriptors:', fds)
 +                return
 +            try:
 +                #
                  # Open a private copy of reader to avoid setting nonblocking
                  # on an unexpecting process with the same reader fd.
 -                self.reader = os.open("/proc/self/fd/%d" % (self.reader),
 +                #
 +                self.reader = os.open(f"/proc/self/fd/{self.reader}",
                                        os.O_RDONLY | os.O_NONBLOCK)
 -
 -            # Read out as many jobserver slots as possible
 -            while True:
 -                try:
 -                    slot = os.read(self.reader, 8)
 -                    if not slot:
 -                        # Clear self.jobs to prevent us from probably writing incorrect file.
 -                        self.jobs = b""
 -                        raise ValueError("unexpected empty token from jobserver fd, invalid '--jobserver-auth=' setting?")
 -                    self.jobs += slot
 -                except (OSError, IOError) as e:
 -                    if e.errno == errno.EWOULDBLOCK:
 -                        # Stop at the end of the jobserver queue.
 -                        break
 -                    # If something went wrong, give back the jobs.
 -                    if self.jobs:
 -                        os.write(self.writer, self.jobs)
 -                    raise e
 -
 -            # Add a bump for our caller's reserveration, since we're just going
 -            # to sit here blocked on our child.
 -            self.claim = len(self.jobs) + 1
 -
 -        except (KeyError, IndexError, ValueError, OSError, IOError) as e:
 -            print(f"jobserver: warning: {repr(e)}", file=sys.stderr)
 -            # Any missing environment strings or bad fds should result in just
 -            # not being parallel.
 -            self.claim = None
 -
 -        self.is_open = True
 +            except (IOError, OSError) as e:
 +                warn('Unable to reopen jobserver read-side pipe:', repr(e))
 +                return
 +        #
 +        # OK, we have the channel to the job server; read out as many jobserver
 +        # slots as possible.
 +        #
 +        while True:
 +            try:
 +                slot = os.read(self.reader, 8)
 +                if not slot:
 +                    #
 +                    # Something went wrong.  Clear self.jobs to avoid writing
 +                    # weirdness back to the jobserver and give up.
 +                    self.jobs = b""
 +                    warn("unexpected empty token from jobserver;"
 +                         " possible invalid '--jobserver-auth=' setting")
 +                    self.claim = None
 +                    return
 +            except (OSError, IOError) as e:
 +                #
 +                # If there is nothing more to read then we are done.
 +                #
 +                if e.errno == errno.EWOULDBLOCK:
 +                    break
 +                #
 +                # Anything else says that something went weird; give back
 +                # the jobs and give up.
 +                #
 +                if self.jobs:
 +                    os.write(self.writer, self.jobs)
 +                    self.claim = None
 +                    warn('error reading from jobserver pipe', repr(e))
 +                    return
 +            self.jobs += slot
 +        #
 +        # Add a bump for our caller's reserveration, since we're just going
 +        # to sit here blocked on our child.
 +        #
 +        self.claim = len(self.jobs) + 1
  
      def close(self):
-         """Return all reserved slots to Jobserver"""
+         """Return all reserved slots to Jobserver."""
  
          if not self.is_open:
              return

diff --cc tools/lib/python/kdoc/kdoc_parser.py
Simple merge