Lines Matching +full:document +full:- +full:file
2 # SPDX-License-Identifier: GPL-2.0
7 Implementation of the ``kernel-include`` reST-directive.
12 The ``kernel-include`` reST-directive is a replacement for the ``include``
13 directive. The ``kernel-include`` directive expand environment variables in
21 tree where the reST document with the include directive is placed.
25 non-existing variables are left unchanged.
30 If present, the included file is inserted as a literal block.
36 Specify the encoding of the included file (default: 'utf-8').
38 :param tab-width:
41 :param start-line:
42 Line number at which to start including the file (1-based).
44 :param end-line:
45 Line number at which to stop including the file (inclusive).
47 :param start-after:
50 :param end-before:
53 :param number-lines:
60 **Kernel-specific Extensions**:
62 :param generate-cross-refs:
63 If present, instead of directly including the file, it calls
64 ParseDataStructs() to convert C data structures into cross-references
67 :param exception-file:
68 (Used with generate-cross-refs)
70 Path to a file containing rules for handling special cases:
71 - Ignore specific C data structures
72 - Use alternative reference names
73 - Specify different reference types
75 :param warn-broken:
76 (Used with generate-cross-refs)
78 Enables warnings when auto-generated cross-references don't point to
109 RE_LINENO_REF = re.compile(r'^\s*-\s+LINENO_(\d+):\s+(.*)')
119 KernelInclude (``kernel-include``) directive
139 'tab-width': int,
140 'start-line': int,
141 'end-line': int,
142 'start-after': directives.unchanged_required,
143 'end-before': directives.unchanged_required,
145 'number-lines': directives.unchanged, # integer or None
149 'generate-cross-refs': directives.flag,
150 'warn-broken': directives.flag,
152 'exception-file': directives.unchanged,
156 """Read and process file content with error handling"""
158 self.state.document.settings.record_dependencies.add(path)
161 … error_handler=self.state.document.settings.input_encoding_error_handler)
164 'Cannot encode input file path "%s" '
176 Handles start-line, end-line, start-after and end-before parameters
179 # Get to-be-included content
180 startline = self.options.get('start-line', None)
181 endline = self.options.get('end-line', None)
189 # start-after/end-before: no restrictions on newlines in match-text,
191 after_text = self.options.get("start-after", None)
196 raise self.severe('Problem with "start-after" option of "%s" '
199 before_text = self.options.get("end-before", None)
204 raise self.severe('Problem with "end-before" option of "%s" '
212 Read and add contents from a C file parsed to have cross references.
215 - A C source code with cross-references;
216 - a TOC table containing cross references.
220 if 'exception-file' in self.options:
223 self.lineno - self.state_machine.input_offset - 1)))
224 exceptions_file = os.path.join(source_dir, self.options['exception-file'])
231 if 'warn-broken' in self.options:
236 rawtext = ".. parsed-literal::\n\n" + parser.gen_output()
248 # TOC output is a ReST file, not a literal. So, we can add line
251 startline = self.options.get('start-line', None)
252 endline = self.options.get('end-line', None)
276 result.append(f"- {ref}: {relpath}#{realln}", path, ln)
294 if "number-lines" in self.options:
296 startline = int(self.options["number-lines"] or 1)
298 raise self.error(":number-lines: with non-integer start value")
301 text = text[:-1]
332 """Include a file as part of the content of this reST file."""
333 env = self.state.document.settings.env
350 raise self.warning(f'File "%s" doesn\'t exist', path)
373 if not self.state.document.settings.file_insertion_enabled:
375 source = self.state_machine.input_lines.source(self.lineno -
376 self.state_machine.input_offset - 1)
380 path = os.path.join(self.standard_include_path, path[1:-1])
387 self.state.document.settings.input_encoding)
388 tab_width = self.options.get("tab-width",
389 self.state.document.settings.tab_width)
391 # Get optional arguments to related to cross-references generation
392 if "generate-cross-refs" in self.options:
431 ref_name = ref_name.split(".")[-1]
446 original_target = original_target.split(".")[-1]
455 # Such method is based on Ratcliff-Obershelp Algorithm, which seeks
475 # Only show missing references for kernel-include reference-parsed files
518 app.connect("env-before-read-docs", init_xref_docs)
519 app.connect("env-merge-info", merge_xref_info)
520 app.add_directive("kernel-include", KernelInclude)
521 app.connect("missing-reference", check_missing_refs)