Lines Matching +full:linkcheck +full:- +full:docs
2 # SPDX-License-Identifier: GPL-2.0
7 # Converted from docs Makefile and parallel-wrapper.sh, both under
22 # Linus Torvalds <torvalds@linux-foundation.org>
36 Sphinx build wrapper that handles Kernel-specific business rules:
38 - it gets the Kernel build environment vars;
39 - it determines what's the best parallelism;
40 - it handles SPHINXDIRS
43 below that, it seeks for a new Python version. If found, it re-runs using
78 "linkcheckdocs": { "builder": "linkcheck" },
96 Handles a sphinx-build target, adding needed arguments to build
137 with open(config, "r", encoding="utf-8") as fp:
150 Get the number of jobs to be used for docs build passed via command
155 1) It can be passed via "-j" argument;
156 2) The SPHINXOPTS="-j8" env var may have "-j";
157 3) if called via GNU make, -j specifies the desired number of jobs.
159 4) if none of the above is available, it should default to "-jauto",
165 # by sphinx-build time. Among them, it may contain sphinx verbosity
169 parser.add_argument('-j', '--jobs', type=int)
170 parser.add_argument('-q', '--quiet', action='store_true')
171 parser.add_argument('-v', '--verbose', default=0, action='count')
174 # Other sphinx-build arguments go as-is, so place them
193 # If the user explicitly sets "-j" at command line, use it.
204 self.sphinxopts += ["-q"]
207 self.sphinxopts += ["-v"]
226 # Several distros package python3xx-sphinx packages with newer
227 # versions of Python and sphinx-build.
236 self.latexopts = os.environ.get("LATEXOPTS", "-interaction=batchmode -no-shell-escape")
263 self.sphinxbuild = os.environ.get("SPHINXBUILD", "sphinx-build")
265 "tools/docs/kernel-doc"))
295 Executes sphinx-build using current python3 command.
299 jobs, as we don't want sphinx-build to run in parallel with other
328 # We can't simply call python3 sphinx-build, as OpenSUSE
330 # between different versions of sphinx-build. So, only call it
339 cmd += [f"-j{n_jobs}"]
388 # any warning makes it non-zero. For kernel doc builds it always return
389 # non-zero even when build succeeds. So, let's do the best next thing:
403 name = name[:-len(tex_suffix)]
463 # deploying variable-font format of "Noto CJK", causing LaTeX
468 # See tools/docs/lib/latex_fonts.py for more details.
480 latex_cmd = [self.latexmk_cmd, f"-{self.pdflatex}"]
509 # used with "-j" and that aren't used by other make targets
576 sys.exit(f"Error generating info docs: {e}")
580 Create man pages from kernel-doc output
583 re_kernel_doc = re.compile(r"^\.\.\s+kernel-doc::\s*(\S+)")
587 # Pick the entire set of kernel-doc markups from the entire tree
595 with open(fname, "r", encoding="utf-8") as in_fp:
605 sys.exit(f"Directory {src_dir} doesn't contain kernel-doc tags")
607 cmd = [ kerneldoc, "-m" ] + sorted(kdoc_files)
615 print(f"Warning: kernel-doc returned {result.returncode} warnings")
639 fp = open(fname, "w", encoding="utf-8")
654 module. It prepares all arguments required by sphinx-build.
661 # Cleandocs doesn't require sphinx-build
671 # Other targets require sphinx-build, so check if it exists
695 # sphinxdirs can be a list or a whitespace-separated string
704 args = [ "-b", builder, "-c", docs_dir ]
710 args.extend(["-D", f"latex_elements.papersize={paper}paper"])
714 args.extend(["-t", "rustdoc"])
717 # The sphinx-build tool has a bug: internally, it tries to set
729 # This is not the best way of handling it, as cross-references between
752 "-d", doctree_dir,
753 "-D", f"version={self.kernelversion}",
754 "-D", f"release={self.kernelrelease}",
755 "-D", f"kerneldoc_srctree={self.srctree}",
781 # sphinx-build finishes
789 print("Building rust docs")
807 Handle valid values for -j. Accepts Sphinx "-jauto", plus a number
828 - KERNELVERSION: Kernel major version
829 - KERNELRELEASE: Kernel release
830 - KBUILD_VERBOSE: Contains the value of "make V=[0|1] variable.
831 When V=0 (KBUILD_VERBOSE=0), sets verbose level to "-q".
832 - SPHINXBUILD: Documentation build tool (default: "sphinx-build").
833 - SPHINXOPTS: Extra options pased to SPHINXBUILD
834 (default: "-j auto" and "-q" if KBUILD_VERBOSE=0).
835 The "-v" flag can be used to increase verbosity.
836 If V=0, the first "-v" will drop "-q".
837 - PYTHON3: Python command to run SPHINXBUILD
838 - PDFLATEX: LaTeX PDF engine. (default: "xelatex")
839 - LATEXOPTS: Optional set of command line arguments to the LaTeX engine
840 - srctree: Location of the Kernel root directory (default: ".").
856 parser.add_argument("--sphinxdirs", nargs="+",
858 parser.add_argument("--builddir", default="output",
861 parser.add_argument("--theme", help="Sphinx theme to use")
863 parser.add_argument("--css", help="Custom CSS file for HTML/EPUB")
865 parser.add_argument("--paper", choices=PAPER, default=PAPER[0],
868 parser.add_argument('--deny-vf',
871 parser.add_argument("-v", "--verbose", action='store_true',
874 parser.add_argument('-j', '--jobs', type=jobs_type,
875 help="Sets number of jobs to use with sphinx-build(default: auto)")
877 parser.add_argument('-i', '--interactive', action='store_true',
880 parser.add_argument('-s', '--skip-sphinx-build', action='store_true',
881 help="Skip sphinx-build step")
883 parser.add_argument("-V", "--venv", nargs='?', const=f'{VENV_DEFAULT}',