tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

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: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <e0ccee75f7e7fb499e0f59d5b84469f4b6a21627.1769500383.git.mchehab+huawei@kernel.org>

authored by

Mauro Carvalho Chehab and committed by
Jonathan Corbet 64e4882c b09cc1dd

+25 -3
+25 -3
tools/docs/sphinx-build-wrapper
··· 814 814 except ValueError: 815 815 raise argparse.ArgumentTypeError(f"Must be 'auto' or positive integer, got {value}") # pylint: disable=W0707 816 816 817 + EPILOG=""" 818 + Besides the command line arguments, several environment variables affect its 819 + default behavior, meant to be used when called via Kernel Makefile: 820 + 821 + - KERNELVERSION: Kernel major version 822 + - KERNELRELEASE: Kernel release 823 + - KBUILD_VERBOSE: Contains the value of "make V=[0|1] variable. 824 + When V=0 (KBUILD_VERBOSE=0), sets verbose level to "-q". 825 + - SPHINXBUILD: Documentation build tool (default: "sphinx-build"). 826 + - SPHINXOPTS: Extra options pased to SPHINXBUILD 827 + (default: "-j auto" and "-q" if KBUILD_VERBOSE=0). 828 + The "-v" flag can be used to increase verbosity. 829 + If V=0, the first "-v" will drop "-q". 830 + - PYTHON3: Python command to run SPHINXBUILD 831 + - PDFLATEX: LaTeX PDF engine. (default: "xelatex") 832 + - LATEXOPTS: Optional set of command line arguments to the LaTeX engine 833 + - srctree: Location of the Kernel root directory (default: "."). 834 + 835 + """ 836 + 817 837 def main(): 818 838 """ 819 839 Main function. The only mandatory argument is the target. If not 820 840 specified, the other arguments will use default values if not 821 841 specified at os.environ. 822 842 """ 823 - parser = argparse.ArgumentParser(description="Kernel documentation builder") 843 + parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter, 844 + description=__doc__, 845 + epilog=EPILOG) 824 846 825 847 parser.add_argument("target", choices=list(TARGETS.keys()), 826 848 help="Documentation target to build") 827 849 parser.add_argument("--sphinxdirs", nargs="+", 828 850 help="Specific directories to build") 829 851 parser.add_argument("--builddir", default="output", 830 - help="Sphinx configuration file") 852 + help="Sphinx configuration file (default: %(default)s)") 831 853 832 854 parser.add_argument("--theme", help="Sphinx theme to use") 833 855 ··· 865 843 help="place build in verbose mode") 866 844 867 845 parser.add_argument('-j', '--jobs', type=jobs_type, 868 - help="Sets number of jobs to use with sphinx-build") 846 + help="Sets number of jobs to use with sphinx-build(default: auto)") 869 847 870 848 parser.add_argument('-i', '--interactive', action='store_true', 871 849 help="Change latex default to run in interactive mode")