Documentation/sphinx/kernel_include.py

Source file repositories/reference/linux-study-clean/Documentation/sphinx/kernel_include.py

File Facts

System
Linux kernel
Corpus path
Documentation/sphinx/kernel_include.py
Extension
.py
Size
19046 bytes
Lines
528
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: Documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-2.0
# pylint: disable=R0903, R0912, R0914, R0915, C0209,W0707


"""
Implementation of the ``kernel-include`` reST-directive.

:copyright:  Copyright (C) 2016  Markus Heiser
:license:    GPL Version 2, June 1991 see linux/COPYING for details.

The ``kernel-include`` reST-directive is a replacement for the ``include``
directive. The ``kernel-include`` directive expand environment variables in
the path name and allows to include files from arbitrary locations.

.. hint::

    Including files from arbitrary locations (e.g. from ``/etc``) is a
    security risk for builders. This is why the ``include`` directive from
    docutils *prohibit* pathnames pointing to locations *above* the filesystem
    tree where the reST document with the include directive is placed.

Substrings of the form $name or ${name} are replaced by the value of
environment variable name. Malformed variable names and references to
non-existing variables are left unchanged.

**Supported Sphinx Include Options**:

:param literal:
    If present, the included file is inserted as a literal block.

:param code:
    Specify the language for syntax highlighting (e.g., 'c', 'python').

:param encoding:
    Specify the encoding of the included file (default: 'utf-8').

:param tab-width:
    Specify the number of spaces that a tab represents.

:param start-line:
    Line number at which to start including the file (1-based).

:param end-line:
    Line number at which to stop including the file (inclusive).

:param start-after:
    Include lines after the first line matching this text.

:param end-before:
    Include lines before the first line matching this text.

:param number-lines:
    Number the included lines (integer specifies start number).
    Only effective with 'literal' or 'code' options.

:param class:
    Specify HTML class attribute for the included content.

**Kernel-specific Extensions**:

:param generate-cross-refs:
    If present, instead of directly including the file, it calls
    ParseDataStructs() to convert C data structures into cross-references
    that link to comprehensive documentation in other ReST files.

:param exception-file:
    (Used with generate-cross-refs)

    Path to a file containing rules for handling special cases:

Annotation

Implementation Notes