sphinx-section-include 2026.11.1__py3-none-any.whl

sphinx_section_include/__init__.py

@@ -0,0 +1,40 @@
+"""Include parsed reStructuredText sections in Sphinx documentation."""
+
+from importlib.metadata import version
+
+from sphinx.application import Sphinx
+
+from sphinx_section_include.directive import (
+    IncludeSection,
+    resolve_included_references,
+)
+from sphinx_section_include.reader import read_document, resolve_source
+from sphinx_section_include.sections import (
+    copy_section,
+    find_sections,
+    select_section,
+)
+
+__all__ = [
+    "copy_section",
+    "find_sections",
+    "read_document",
+    "resolve_source",
+    "select_section",
+]
+__version__ = version(distribution_name="sphinx-section-include")
+
+
+def setup(app: Sphinx) -> dict[str, object]:
+    """Register the directive and builder-independent reference
+    handling.
+    """
+    app.add_directive(name="include-section", cls=IncludeSection)
+    _ = app.connect(
+        event="doctree-resolved", callback=resolve_included_references
+    )
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

sphinx_section_include/directive.py

@@ -0,0 +1,232 @@
+"""Expose parsed section inclusion as a Sphinx directive."""
+
+import posixpath
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, ClassVar, override
+from urllib.parse import urlsplit
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+from sphinx import addnodes
+from sphinx.application import Sphinx
+from sphinx.errors import NoUri
+from sphinx.util import docname_join
+from sphinx.util.docutils import SphinxDirective
+
+from sphinx_section_include.reader import read_document, resolve_source
+from sphinx_section_include.sections import copy_section, select_section
+
+
+def _prepare_nodes(
+    *,
+    directive: SphinxDirective,
+    content: list[nodes.Node],
+    source_docname: str,
+) -> list[nodes.Node]:
+    """Prefix copied targets and retain external reference origins."""
+    container = nodes.container()
+    container.extend(item=content)
+    serial = directive.env.new_serialno(category="section-include")
+    prefix = f"section-include-{serial}-"
+    elements = list(container.findall(condition=nodes.Element))
+    identities = {
+        identity: prefix + identity
+        for element in elements
+        for identity in element["ids"]
+    }
+    names = {
+        name: prefix + name
+        for element in elements
+        for name in element["names"]
+    }
+    for element in elements:
+        element["ids"] = [identities[identity] for identity in element["ids"]]
+        element["names"] = [names[name] for name in element["names"]]
+        if bool(element["ids"]) or bool(element["names"]):
+            directive.state.document.note_explicit_target(target=element)
+        element.document = directive.state.document
+        if isinstance(element, addnodes.pending_xref):
+            _prepare_cross_reference(
+                reference=element,
+                names=names,
+                source_docname=source_docname,
+                docname=directive.env.docname,
+            )
+        if isinstance(element, nodes.reference):
+            _prepare_reference(
+                reference=element,
+                identities=identities,
+                source_docname=source_docname,
+            )
+        if isinstance(element, nodes.image):
+            _prepare_image(
+                image=element,
+                directive=directive,
+                source_docname=source_docname,
+            )
+    return container.children
+
+
+def _prepare_cross_reference(
+    *,
+    reference: addnodes.pending_xref,
+    names: dict[str, str],
+    source_docname: str,
+    docname: str,
+) -> None:
+    """Keep Sphinx roles tied to their selected target or original
+    document.
+    """
+    if reference.get(key="refdomain") == "std":
+        if (
+            reference.get(key="reftype") == "ref"
+            and reference["reftarget"] in names
+        ):
+            reference["reftarget"] = names[reference["reftarget"]]
+        elif reference.get(key="reftype") == "doc":
+            reference["reftarget"] = "/" + docname_join(
+                basedocname=source_docname, docname=reference["reftarget"]
+            )
+    reference["refdoc"] = docname
+
+
+def _is_relative_uri(*, uri: str) -> bool:
+    """Recognize local links without schemes, hosts, or rooted paths."""
+    parsed = urlsplit(url=uri)
+    return (
+        not bool(parsed.scheme)
+        and not bool(parsed.netloc)
+        and not parsed.path.startswith("/")
+    )
+
+
+def _prepare_reference(
+    *,
+    reference: nodes.reference,
+    identities: dict[str, str],
+    source_docname: str,
+) -> None:
+    """Distinguish anchors inside the excerpt from links to its source."""
+    if "refid" in reference:
+        target = reference["refid"]
+        if target in identities:
+            reference["refid"] = identities[target]
+        else:
+            del reference["refid"]
+            _ = reference.setdefault(
+                key="section_include_origin", failobj=source_docname
+            )
+            reference["section_include_anchor"] = target
+    elif "refuri" in reference and _is_relative_uri(uri=reference["refuri"]):
+        _ = reference.setdefault(
+            key="section_include_origin", failobj=source_docname
+        )
+
+
+def _prepare_image(
+    *,
+    image: nodes.image,
+    directive: SphinxDirective,
+    source_docname: str,
+) -> None:
+    """Resolve local image paths before the caller collects image
+    assets.
+    """
+    if not _is_relative_uri(uri=image["uri"]):
+        return
+    origin = Path(
+        image.source
+        if image.source is not None
+        else directive.env.doc2path(docname=source_docname)
+    )
+    relative = (
+        origin.parent.resolve()
+        .relative_to(Path(directive.env.srcdir).resolve())
+        .as_posix()
+    )
+    image["uri"] = "/" + posixpath.normpath(
+        path=posixpath.join(relative, str(object=image["uri"]))
+    )
+
+
+def resolve_included_references(
+    app: Sphinx, doctree: nodes.document, docname: str
+) -> None:
+    """Resolve source links using the active builder's URI conventions."""
+    for reference in doctree.findall(condition=nodes.reference):
+        origin = reference.get(key="section_include_origin")
+        if origin is None:
+            continue
+        try:
+            base = app.builder.get_relative_uri(from_=docname, to=origin)
+        except NoUri:
+            reference.replace_self(new=reference.children)
+            continue
+        anchor = reference.get(key="section_include_anchor")
+        if anchor is not None:
+            reference["refuri"] = base + "#" + anchor
+        else:
+            # Keep paths relative to the original rendered document.
+
+            parsed = urlsplit(url=str(object=reference["refuri"]))
+            path = (
+                posixpath.normpath(
+                    path=posixpath.join(posixpath.dirname(base), parsed.path)
+                )
+                if bool(parsed.path)
+                else base
+            )
+            if parsed.path.endswith("/") and not path.endswith("/"):
+                path += "/"
+            reference["refuri"] = parsed._replace(path=path).geturl()
+
+
+class IncludeSection(SphinxDirective):
+    """Include one exact section while preserving its document
+    structure.
+    """
+
+    required_arguments = 1
+    option_spec: ClassVar[dict[str, Callable[[str], Any]] | None] = {  # pyrefly: ignore[explicit-any]
+        "section": directives.unchanged_required,
+        "include-heading": directives.flag,
+        "exclude-sections": directives.unchanged_required,
+    }
+
+    @override
+    def run(self) -> list[nodes.Node]:
+        """Read, select, and copy a section without rendering it to
+        HTML.
+        """
+        if "section" not in self.options:
+            raise self.error(message="include-section requires :section:")
+        try:
+            path = resolve_source(directive=self, source=self.arguments[0])
+            document = read_document(directive=self, source=self.arguments[0])
+            selected = select_section(
+                document=document, selector=self.options["section"]
+            )
+            excluded = tuple(
+                select_section(document=selected, selector=selector.strip())
+                for selector in self.options.get(
+                    "exclude-sections", ""
+                ).splitlines()
+                if bool(selector.strip())
+            )
+            content = copy_section(
+                section=selected,
+                include_heading="include-heading" in self.options,
+                exclude_sections=excluded,
+            )
+            return _prepare_nodes(
+                directive=self,
+                content=content,
+                source_docname=path.relative_to(
+                    Path(self.env.srcdir).resolve()
+                )
+                .with_suffix(suffix="")
+                .as_posix(),
+            )
+        except ValueError as error:
+            raise self.error(message=str(object=error)) from error

sphinx_section_include/reader.py

@@ -0,0 +1,110 @@
+"""Read source documents through the active Sphinx directive context."""
+
+from copy import copy
+from pathlib import Path
+
+from docutils import nodes
+from docutils.parsers.rst import Parser
+from docutils.transforms.references import (
+    AnonymousHyperlinks,
+    DanglingReferences,
+    ExternalTargets,
+    IndirectHyperlinks,
+    InternalTargets,
+    PropagateTargets,
+    Substitutions,
+)
+from docutils.utils import new_document
+from sphinx.transforms import DefaultSubstitutions
+from sphinx.util.docutils import LoggingReporter, SphinxDirective
+
+
+def resolve_source(*, directive: SphinxDirective, source: str) -> Path:
+    """Resolve an RST source inside the Sphinx source directory."""
+    root = Path(directive.env.srcdir).resolve()
+    _relative, filename = directive.env.relfn2path(filename=source)
+    path = Path(filename).resolve()
+    if not path.is_relative_to(root) or path.suffix != ".rst":
+        message = (
+            "Section source must be an RST file within the source directory"
+        )
+        raise ValueError(message)
+    current = Path(
+        directive.env.doc2path(docname=directive.env.docname)
+    ).resolve()
+    if path == current:
+        message = "A section include cannot include itself"
+        raise ValueError(message)
+    if not path.is_file():
+        message = f"Section source does not exist: {source!r}"
+        raise ValueError(message)
+    return path
+
+
+def read_document(
+    *, directive: SphinxDirective, source: str, docname: str | None = None
+) -> nodes.document:
+    """Parse source content and record its transitive include dependencies.
+
+    Registered directives, substitutions, and the caller's Sphinx configuration
+    remain available. Source-relative includes use the source document's path.
+    Temporary parsing context is restored even if parsing fails.
+    """
+    path = resolve_source(directive=directive, source=source)
+    root = Path(directive.env.srcdir).resolve()
+    parent = directive.state.document
+    ancestors = tuple[str, ...](
+        parent.get(key="_section_include_sources", failobj=())
+    )
+    if str(object=path) in ancestors:
+        message = f"Circular section include involving {path.name!r}"
+        raise ValueError(message)
+    settings = copy(x=parent.settings)
+    document = new_document(
+        source_path=str(
+            object=directive.env.doc2path(
+                docname=directive.env.docname if docname is None else docname
+            )
+        ),
+        settings=settings,
+    )
+    document.reporter = LoggingReporter.from_reporter(
+        reporter=document.reporter
+    )
+    document["_section_include_sources"] = (*ancestors, str(object=path))
+    relative = path.relative_to(root).as_posix()
+    env = directive.env
+    current = env.current_document
+    source_docname = path.relative_to(root).with_suffix(suffix="").as_posix()
+    context = copy(x=current)
+    context.docname = source_docname if docname is None else docname
+    env.note_dependency(filename=path)
+    env.current_document = context
+    try:
+        text = "\n\n".join(
+            part
+            for part in (
+                directive.config.rst_prolog or "",
+                f".. include:: /{relative}",
+                directive.config.rst_epilog or "",
+            )
+            if bool(part)
+        )
+        Parser().parse(inputstring=text, document=document)
+        for transform in (
+            DefaultSubstitutions,
+            Substitutions,
+            PropagateTargets,
+            AnonymousHyperlinks,
+            IndirectHyperlinks,
+            ExternalTargets,
+            InternalTargets,
+            DanglingReferences,
+        ):
+            transform(document=document).apply()
+    finally:
+        env.current_document = current
+        env.dependencies[current.docname].update(
+            env.dependencies[context.docname]
+        )
+    return document

sphinx_section_include/sections.py

@@ -0,0 +1,78 @@
+"""Select and copy parsed sections without imposing presentation
+policy.
+"""
+
+from docutils import nodes
+
+
+def find_sections(
+    *, document: nodes.document | nodes.section, selector: str
+) -> list[nodes.section]:
+    """Find literal headings, heading paths, or standard RST labels.
+
+    Literal headings take precedence over path or label syntax.
+    """
+    sections = list(document.findall(condition=nodes.section))
+    literal = [
+        section for section in sections if section[0].astext() == selector
+    ]
+    if bool(literal):
+        return literal
+    if selector.startswith("#"):
+        label = nodes.fully_normalize_name(name=selector[1:])
+        return [
+            section
+            for section in sections
+            if label in section["names"] or label in section["ids"]
+        ]
+    parts = [part.strip() for part in selector.split(sep="/")]
+    matches: list[nodes.section] = [
+        section for section in sections if section[0].astext() == parts[0]
+    ]
+    for part in parts[1:]:
+        matches = [
+            child
+            for section in matches
+            for child in section.children
+            if isinstance(child, nodes.section) and child[0].astext() == part
+        ]
+    return matches
+
+
+def select_section(
+    *, document: nodes.document | nodes.section, selector: str
+) -> nodes.section:
+    """Require exactly one matching section."""
+    matches = find_sections(document=document, selector=selector)
+    if len(matches) != 1:
+        message = (
+            f"Expected one section for {selector!r}, found {len(matches)}"
+        )
+        raise ValueError(message)
+    return matches[0]
+
+
+def copy_section(
+    *,
+    section: nodes.section,
+    include_heading: bool = True,
+    exclude_sections: tuple[nodes.section, ...] = (),
+) -> list[nodes.Node]:
+    """Copy a subtree, preserving headings, anchors, and source metadata.
+
+    Exclusions must be resolved descendants of the selected section.
+    The source tree is never modified.
+    """
+    originals = list(section.findall(condition=nodes.section))
+    identities = {id(node) for node in originals if node is not section}
+    if any(id(node) not in identities for node in exclude_sections):
+        message = "Excluded sections must be descendants of the selection"
+        raise ValueError(message)
+    copied = section.deepcopy()
+    copies = list(copied.findall(condition=nodes.section))
+    excluded = {id(node) for node in exclude_sections}
+    for original, target in zip(originals, copies, strict=True):
+        if id(original) in excluded:
+            assert target.parent is not None
+            _ = target.parent.remove(item=target)
+    return [copied] if include_heading else copied.children[1:]

sphinx_section_include-2026.11.1.dist-info/METADATA

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: sphinx-section-include
+Version: 2026.11.1
+Summary: Include selected sections of reStructuredText documents in Sphinx projects.
+Author-email: Adam Dangoor <adamdangoor@gmail.com>
+License-Expression: MIT
+Project-URL: Issues, https://github.com/adamtheturtle/sphinx-section-include/issues
+Project-URL: Source, https://github.com/adamtheturtle/sphinx-section-include
+Keywords: documentation,rst,sphinx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.12
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: docutils>=0.21.2
+Requires-Dist: sphinx<10,>=9.1.1
+Dynamic: license-file
+
+|Build Status| |PyPI|
+
+sphinx-section-include
+======================
+
+Include selected sections of reStructuredText documents in Sphinx projects.
+The extension copies parsed nodes, retaining nested headings, code blocks, source locations, and references.
+It also provides a typed Python API for extensions that select and transform sections themselves.
+
+Installation
+------------
+
+.. code-block:: console
+
+   $ pip install sphinx-section-include
+
+Enable the extension in ``conf.py``:
+
+.. code-block:: python
+
+   """Enable section inclusion in this Sphinx project."""
+
+   extensions = ["sphinx_section_include"]
+
+Including a section
+-------------------
+
+.. code-block:: rst
+
+   .. include-section:: manual.rst
+      :section: Getting started / Configuration
+      :include-heading:
+      :exclude-sections: Advanced configuration
+
+``:section:`` is required.
+It accepts an exact heading, a slash-separated heading path, or an RST label prefixed by ``#``.
+Literal heading matches take precedence, so headings containing slashes remain selectable.
+Missing or ambiguous selections fail with a build diagnostic.
+
+``:include-heading:`` includes the selected section's heading.
+Without it, only the section's contents and nested sections are included.
+``:exclude-sections:`` accepts one descendant selector per line.
+
+Paths are relative to the including document.
+A leading ``/`` selects a path relative to the Sphinx source directory.
+Sources must be existing ``.rst`` files within that directory.
+Self-inclusion and circular section includes are rejected.
+
+Source documents are parsed with registered directives, substitutions, ``rst_prolog``, and ``rst_epilog``.
+Dependencies from nested includes are tracked for incremental builds.
+Internal anchors are namespaced so the same section can appear more than once.
+Links outside the excerpt retain their source document, and local image paths retain their source directory.
+Standard Sphinx reference resolution and builder URI conventions apply.
+
+Python API
+----------
+
+``find_sections(document=..., selector=...)`` returns all matching sections.
+``select_section(document=..., selector=...)`` requires exactly one match and raises ``ValueError`` otherwise.
+
+``copy_section(section=..., include_heading=True, exclude_sections=())`` returns independent copied nodes without modifying the source tree.
+Exclusions are resolved section nodes and must be descendants of the selection.
+This function preserves document structure and does not apply rendering policy.
+
+For Sphinx directive authors, ``read_document(directive=..., source=..., docname=None)`` parses an RST source and records its dependencies.
+The default parsing context is the source document.
+A ``docname`` override supports extensions whose embedded content uses the caller's context.
+Temporary context is restored after parsing.
+``resolve_source(directive=..., source=...)`` validates and resolves the path.
+Both helpers require an active Sphinx build, which supplies the source directory and directive context.
+
+This library was extracted from `sphinx-hackerrank <https://github.com/adamtheturtle/sphinx-hackerrank>`_.
+HackerRank layouts, language filtering, and HTML export remain in that extension.
+
+Development
+-----------
+
+See `CONTRIBUTING.rst <CONTRIBUTING.rst>`_ for local checks and release steps.
+The sample project exercises section inclusion without HackerRank dependencies.
+
+License
+-------
+
+MIT.
+See ``LICENSE``.
+
+.. |Build Status| image:: https://github.com/adamtheturtle/sphinx-section-include/actions/workflows/ci.yml/badge.svg?branch=main
+   :target: https://github.com/adamtheturtle/sphinx-section-include/actions
+.. |PyPI| image:: https://badge.fury.io/py/sphinx-section-include.svg
+   :target: https://badge.fury.io/py/sphinx-section-include

sphinx_section_include-2026.11.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+sphinx_section_include/__init__.py,sha256=0eEbZPjCobVcfti28Th061whDkLmKJsqUkMgzttl9sQ,1039
+sphinx_section_include/directive.py,sha256=gYKXYioqo6ZrXr_kyFCBXP7r3FErucjk0qipquKnbXY,7917
+sphinx_section_include/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sphinx_section_include/reader.py,sha256=Td25MC7Svl0fz7ZDREcdeolV6us_TuKcDAKRL1o5D0o,3870
+sphinx_section_include/sections.py,sha256=XfBIao0a_oLPgE8uoC6lkhDErwev1M3fHaSJb6w3JWU,2722
+sphinx_section_include-2026.11.1.dist-info/licenses/LICENSE,sha256=hvkADUCIndXpdC1L7yhnIKS99N0Wdtaf9YF06bRgZCo,1065
+sphinx_section_include-2026.11.1.dist-info/METADATA,sha256=A5JdBWkjwmSBJifir5wO4euvW42K_Uew5_0Lz6l6Ieo,4847
+sphinx_section_include-2026.11.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+sphinx_section_include-2026.11.1.dist-info/top_level.txt,sha256=MoKTLpvbIddgffcyurFCklHI2C5p-2HCYu314x92xdM,23
+sphinx_section_include-2026.11.1.dist-info/RECORD,,

sphinx_section_include-2026.11.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sphinx_section_include-2026.11.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rippling
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sphinx_section_include-2026.11.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+sphinx_section_include