Commit 64e4882c authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet
Browse files

tools: sphinx-build-wrapper: improve its help message 



Besides the parameters that are passed via command line arguments,
the wrapper's behavior is affected by several environment variables.

Document that. While here, use __doc__ for its description.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
Message-ID: <e0ccee75f7e7fb499e0f59d5b84469f4b6a21627.1769500383.git.mchehab+huawei@kernel.org>
parent b09cc1dd

tools/docs/sphinx-build-wrapper

+25 −3
Original line number Diff line number Diff line
@@ -814,20 +814,42 @@ def jobs_type(value): 
    except ValueError:

        raise argparse.ArgumentTypeError(f"Must be 'auto' or positive integer, got {value}")  # pylint: disable=W0707



EPILOG="""

Besides the command line arguments, several environment variables affect its

default behavior, meant to be used when called via Kernel Makefile:



- KERNELVERSION:  Kernel major version

- KERNELRELEASE:  Kernel release

- KBUILD_VERBOSE: Contains the value of "make V=[0|1] variable.

                  When V=0 (KBUILD_VERBOSE=0), sets verbose level to "-q".

- SPHINXBUILD:    Documentation build tool (default: "sphinx-build").

- SPHINXOPTS:     Extra options pased to SPHINXBUILD

                  (default: "-j auto" and "-q" if KBUILD_VERBOSE=0).

                  The "-v" flag can be used to increase verbosity.

                  If V=0, the first "-v" will drop "-q".

- PYTHON3:        Python command to run SPHINXBUILD

- PDFLATEX:       LaTeX PDF engine. (default: "xelatex")

- LATEXOPTS:      Optional set of command line arguments to the LaTeX engine

- srctree:        Location of the Kernel root directory (default: ".").



"""



def main():

    """

    Main function. The only mandatory argument is the target. If not

    specified, the other arguments will use default values if not

    specified at os.environ.

    """

    parser = argparse.ArgumentParser(description="Kernel documentation builder")

    parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter,

                                     description=__doc__,

                                     epilog=EPILOG)



    parser.add_argument("target", choices=list(TARGETS.keys()),

                        help="Documentation target to build")

    parser.add_argument("--sphinxdirs", nargs="+",

                        help="Specific directories to build")

    parser.add_argument("--builddir", default="output",

                        help="Sphinx configuration file")

                        help="Sphinx configuration file (default: %(default)s)")



    parser.add_argument("--theme", help="Sphinx theme to use")
@@ -843,7 +865,7 @@ def main(): 
                        help="place build in verbose mode")



    parser.add_argument('-j', '--jobs', type=jobs_type,

                        help="Sets number of jobs to use with sphinx-build")

                        help="Sets number of jobs to use with sphinx-build(default: auto)")



    parser.add_argument('-i', '--interactive', action='store_true',

                        help="Change latex default to run in interactive mode")