sphinxcontrib-rust 0.1.0__py3-none-any.whl

sphinxcontrib_rust/__init__.py

@@ -0,0 +1,97 @@
+"""Init module for the extension with the ``setup`` function used by Sphinx"""
+
+from importlib.metadata import version
+import subprocess
+from shutil import which
+from typing import Any, Mapping
+
+import sphinx.config
+from sphinx.application import Sphinx
+from sphinx.util import logging
+
+from sphinxcontrib_rust.domain import RustDomain
+
+__PKG_NAME = "sphinxcontrib_rust"
+__VERSION__ = version(__PKG_NAME)
+__REQUIRED_EXTENSIONS = ["sphinx.ext.autodoc"]
+__LOGGER = logging.getLogger(__PKG_NAME)
+
+"""The configuration options added by the extension.
+
+Each entry is tuple consisting of
+* The option name.
+* The default value.
+* The rebuild condition .
+  * "html": Change needs a full rebuild of HTML.
+  * "env": Change needs a full rebuild of the build environment.
+  * "": No rebuild required.
+* A list of types for the value.
+"""
+__CONFIG_OPTIONS = (
+    ("rust_crates", None, "env", [dict]),
+    ("rust_doc_dir", None, "env", [str]),
+    ("rust_rustdoc_fmt", "rst", "env", [str]),
+    ("rust_visibility", "pub", "html", [str]),  # TODO: Define a type for this
+)
+
+"""
+See https://www.sphinx-doc.org/en/master/extdev/index.html#extension-metadata
+"""
+__METADATA = {
+    "version": __VERSION__,
+    "parallel_read_safe": True,
+    "parallel_write_safe": True,
+}
+__RUSTDOCGEN = which("sphinx-rustdocgen")
+
+
+def generate_docs(app: Sphinx, config: sphinx.config.Config):
+    """Generate the Rust docs once the configuration has been read
+
+    Args:
+        :app: The Sphinx application.
+        :config: The parsed configuration.
+    """
+    for crate, src_dir in config.rust_crates.items():
+        __LOGGER.info(
+            "[sphinxcontrib_rust] Processing contents of crate %s from directory %s",
+            crate,
+            src_dir,
+        )
+        __LOGGER.info(
+            "[sphinxcontrib_rust] Generated files will be saved in %s/%s",
+            config.rust_doc_dir,
+            crate,
+        )
+        subprocess.run(
+            [
+                __RUSTDOCGEN,
+                crate,
+                src_dir,
+                config.rust_doc_dir,
+                config.rust_rustdoc_fmt,
+            ],
+            check=True,
+        )
+
+
+def setup(app: Sphinx) -> Mapping[str, Any]:
+    """Set up the extension"""
+    if __RUSTDOCGEN is None:
+        raise ValueError(
+            "Could not find the sphinx-rustdocgen executable. "
+            "Make sure it is installed and available on the default PATH."
+        )
+
+    app.require_sphinx("7.0")
+
+    for extension in __REQUIRED_EXTENSIONS:
+        app.setup_extension(extension)
+
+    for option in __CONFIG_OPTIONS:
+        app.add_config_value(*option)
+
+    app.add_domain(RustDomain)
+    app.connect("config-inited", generate_docs)
+
+    return __METADATA

sphinxcontrib_rust/directives.py

@@ -0,0 +1,250 @@
+"""
+The module provides all the directive classes for the Rust object types.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Sequence, Type
+
+from docutils.parsers.rst import directives
+from sphinx import addnodes
+from sphinx.addnodes import desc_signature
+from sphinx.directives import (
+    ObjDescT,
+    ObjectDescription,
+    nl_escape_re,
+    strip_backslash_re,
+)
+from sphinx.util.nodes import make_id
+
+from sphinxcontrib_rust.items import RustItem, RustItemType
+
+
+class RustDirective(ABC, ObjectDescription[Sequence[str]]):
+    """Base class for Rust directives"""
+
+    option_spec = {
+        "no-index": directives.flag,
+        "vis": directives.unchanged_required,
+        "sig": directives.unchanged,
+        "toc": directives.unchanged,
+        "type": directives.unchanged,
+    }
+
+    @property
+    @abstractmethod
+    def rust_item_type(self) -> RustItemType:
+        """The Rust object type for the directive"""
+        raise NotImplementedError
+
+    @classmethod
+    def get_directives(cls) -> dict[RustItemType, Type["RustDirective"]]:
+        """Get all the directives for the object types"""
+        return {
+            RustItemType.CRATE: RustCrateDirective,
+            RustItemType.ENUM: RustEnumDirective,
+            RustItemType.FUNCTION: RustFunctionDirective,
+            RustItemType.IMPL: RustImplDirective,
+            RustItemType.MACRO: RustMacroDirective,
+            RustItemType.MODULE: RustModuleDirective,
+            RustItemType.STRUCT: RustStructDirective,
+            RustItemType.TRAIT: RustTraitDirective,
+            RustItemType.TYPE: RustTypeDirective,
+            RustItemType.VARIABLE: RustVariableDirective,
+        }
+
+    def add_target_and_index(
+        self, name: Sequence[str], sig: str, signode: desc_signature
+    ) -> None:
+        """Adds the item to the domain and generates the index for it.
+
+        This is called after :py:func:`handle_signature` has executed.
+
+        Args:
+            :name: The name of the item, which is the return value from
+                :py:func:`handle_signature`.
+            :sig: The argument to the directive, which is the Rust path
+                of the item set by the Rust doc generator.
+            :signode: The docutils node of the for item.
+        """
+        fullname = "::".join(name)  # XXX: Can we just use sig here?
+        node_id = make_id(self.env, self.state.document, "", fullname)
+        signode["ids"].append(node_id)
+
+        rust_obj = RustItem(
+            name=fullname,
+            dispname=self.options.get("sig", name[-1]),
+            type_=self.rust_item_type,
+            docname=self.env.docname,
+            anchor="-".join(name),  # Need to join with - for HTML anchors
+        )
+
+        # Add to the domain
+        self.env.domains["rust"].data[self.rust_item_type].append(rust_obj)
+
+        if "no-index" not in self.options:
+            self.indexnode["entries"].append(("single", fullname, node_id, "", None))
+
+    def get_signatures(self) -> list[str]:
+        """Override the default get_signatures method, which splits the signatures by line.
+
+        Currently, only one signature is allowed for each Rust object, and due to the use
+        of where on new lines, it is all part of one signature. Only the final newline is
+        removed.
+
+        See Also:
+            * `Docs for the method`_
+            * `Source code for super`_
+
+        .. _`Docs for the method`:
+            https://www.sphinx-doc.org/en/master/_modules/sphinx/directives.html#ObjectDescription.get_signatures
+        .. _`Source code for super`:
+            https://www.sphinx-doc.org/en/master/_modules/sphinx/directives.html#ObjectDescription.get_signatures
+        """
+        sig = nl_escape_re.sub("", self.arguments[0]).strip()
+        return (
+            [strip_backslash_re.sub(r"\1", sig)]
+            if self.config.strip_signature_backslash
+            else [sig]
+        )
+
+    def handle_signature(self, sig: str, signode: addnodes.desc_signature) -> ObjDescT:
+        """Handle the directive and generate its display signature.
+
+        The display signature is what is displayed instead of the directive name and
+        options in the generated output. The ``:sig:`` option of the directive is used
+        to override the provided ``sig`` value. If the option is not set, the item type
+        and the final component of the path are used.
+
+        Raising ``ValueError`` will put the ``sig`` value into a single node, which
+        is what the super implementation does.
+
+        Args:
+            :sig: The argument of the directive as set during doc generation, not the
+                ``:sig:`` option. The Rust side of the code will put the full Rust path
+                of the item as the argument.
+            :signode: The docutils node for the item, to which the display signature nodes
+                should be appended.
+
+        Returns:
+            The path for the object, which is a tuple of the Rust path components and
+            defines the hierarchy of the object for indexing.
+        """
+        path = tuple(sig.split("::"))
+        # TODO: Parse the signature as RST content and handle multi-line
+        signode += addnodes.desc_name(
+            sig,
+            self.options.get("sig", f"{self.rust_item_type.display_name} {path[-1]}"),
+        )
+        signode.path = path
+        return path
+
+    def _object_hierarchy_parts(
+        self, sig_node: addnodes.desc_signature
+    ) -> tuple[str, ...]:
+        """Returns the hierarchy of the object for indexing and de-duplication.
+
+        Args:
+            :sig_node: The docutils node of the for item.
+
+        Returns:
+            A tuple of the Rust path for the item, as set during the
+            doc generation.
+        """
+        return sig_node.path
+
+    def _toc_entry_name(self, sig_node: addnodes.desc_signature) -> str:
+        """Generate the TOC entry for the item.
+
+        For most directives, this is just the item type and identifier of the
+        item. The ``:toc:`` option is set during doc generation where that is
+        not sufficient (``impl`` blocks) or not desired (enum variants).
+
+        Args:
+            sig_node: The docutils node for the item.
+
+        Returns:
+            The text to display for the item in the TOC and sidebar.
+        """
+        return self.options.get(
+            "toc", f"{self.rust_item_type.display_name} {sig_node.path[-1]}"
+        )
+
+
+class RustCrateDirective(RustDirective):
+    """Directive for handling crate documentation"""
+
+    @property
+    def rust_item_type(self) -> RustItemType:
+        return RustItemType.CRATE
+
+
+class RustEnumDirective(RustDirective):
+    """Directive for handling enum documentation"""
+
+    @property
+    def rust_item_type(self) -> RustItemType:
+        return RustItemType.ENUM
+
+
+class RustFunctionDirective(RustDirective):
+    """Directive for handling function documentation"""
+
+    @property
+    def rust_item_type(self) -> RustItemType:
+        return RustItemType.FUNCTION
+
+
+class RustImplDirective(RustDirective):
+    """Directive for handling function documentation"""
+
+    @property
+    def rust_item_type(self) -> RustItemType:
+        return RustItemType.IMPL
+
+
+class RustMacroDirective(RustDirective):
+    """Directive for handling function documentation"""
+
+    @property
+    def rust_item_type(self) -> RustItemType:
+        return RustItemType.MACRO
+
+
+class RustModuleDirective(RustDirective):
+    """Directive for handling module documentation"""
+
+    @property
+    def rust_item_type(self) -> RustItemType:
+        return RustItemType.MODULE
+
+
+class RustStructDirective(RustDirective):
+    """Directive for handling struct documentation"""
+
+    @property
+    def rust_item_type(self) -> RustItemType:
+        return RustItemType.STRUCT
+
+
+class RustTraitDirective(RustDirective):
+    """Directive for handling trait documentation"""
+
+    @property
+    def rust_item_type(self) -> RustItemType:
+        return RustItemType.TRAIT
+
+
+class RustTypeDirective(RustDirective):
+    """Directive for handling type documentation"""
+
+    @property
+    def rust_item_type(self) -> RustItemType:
+        return RustItemType.TYPE
+
+
+class RustVariableDirective(RustDirective):
+    """Directive for handling type documentation"""
+
+    @property
+    def rust_item_type(self) -> RustItemType:
+        return RustItemType.VARIABLE

sphinxcontrib_rust/domain.py

@@ -0,0 +1,209 @@
+"""
+The module defines the :py:class:`RustDomain` class, which is a Sphinx domain
+for the various concepts used within the Rust programming language.
+"""
+
+from typing import Optional, Type, Union, Iterable
+
+from docutils.nodes import Element
+from docutils.parsers.rst import Directive
+from sphinx.addnodes import pending_xref
+from sphinx.builders import Builder
+from sphinx.domains import Domain, Index, ObjType
+from sphinx.environment import BuildEnvironment
+from sphinx.roles import XRefRole
+from sphinx.util import logging
+from sphinx.util.nodes import make_refnode
+from sphinx.util.typing import RoleFunction
+
+from sphinxcontrib_rust.directives import RustDirective
+from sphinxcontrib_rust.index import (
+    CrateIndex,
+    EnumIndex,
+    FunctionIndex,
+    ModuleIndex,
+    StructIndex,
+    TraitIndex,
+    TypeIndex,
+    VariableIndex,
+)
+from sphinxcontrib_rust.items import RustItem, RustItemType
+
+LOGGER = logging.getLogger(__name__)
+
+
+class RustXRefRole(XRefRole):
+    """An :py:class:`XRefRole` extension for Rust roles"""
+
+    def process_link(
+        self,
+        env: BuildEnvironment,
+        refnode: Element,
+        has_explicit_title: bool,
+        title: str,
+        target: str,
+    ) -> tuple[str, str]:
+        """Process the link by parsing the tile and the target"""
+        # pylint: disable=too-many-arguments
+        if not has_explicit_title:
+            # This is the most common case where
+            # only the target is specified as the title like
+            # `` :rust:struct:`~crate::module::Struct` ``
+            # title == target in this case
+
+            # Remove any leading or trailing ::s.
+            # Only meaningful for targets, once support
+            # for relative references is added.
+            title = title.strip("::")
+
+            # Remove the ~ from the target, only meaningful for titles.
+            target = target.lstrip("~")
+
+            # ~ will use only the final part of the name as the title
+            # instead of the full path.
+            if title[0:1] == "~":
+                title = title[1:]
+                sep = title.rfind("::")
+                if sep != -1:
+                    title = title[sep + 2 :]
+
+        return title, target
+
+
+class RustDomain(Domain):
+    """The Sphinx domain for the Rust programming language.
+
+    The domain provides the various roles and directives that can be used in the Sphinx
+    documentation for linking with Rust code.
+    """
+
+    name = "rust"
+    label = "Rust"
+
+    # The various object types provided by the domain
+    object_types: dict[str, ObjType] = {
+        t.value: t.get_sphinx_obj_type() for t in RustItemType
+    }
+
+    # The various directives add to Sphinx for documenting the Rust object types
+    directives: dict[str, Type[Directive]] = {
+        t.value: d for t, d in RustDirective.get_directives().items()
+    }
+
+    # The various roles added to Sphinx for referencing the Rust object types
+    roles: dict[str, Union[RoleFunction, XRefRole]] = {
+        # TODO: Customize this role
+        r: RustXRefRole()
+        for _, r in RustItemType.iter_roles()
+    }
+
+    # The indices for all the object types
+    indices: list[Type[Index]] = [
+        CrateIndex,
+        ModuleIndex,
+        StructIndex,
+        TraitIndex,
+        EnumIndex,
+        FunctionIndex,
+        VariableIndex,
+        TypeIndex,
+    ]
+
+    # The domain data created by Sphinx. This is here just for type annotation.
+    data: dict[RustItemType, list[RustItem]]
+
+    # Initial data for the domain, gets copied as self.data by Sphinx
+    initial_data: dict[RustItemType, list[RustItem]] = {
+        t: [] for t in RustItemType
+    }  # XXX: Perhaps better to create dict instead of list and key by name.
+
+    # Bump this when the data format changes.
+    data_version = 0
+
+    def get_objects(self) -> Iterable[tuple[str, str, str, str, str, int]]:
+        for typ, objs in self.data.items():
+            if not isinstance(typ, RustItemType):
+                continue
+            for obj in objs:
+                yield (
+                    obj.name,
+                    obj.dispname,
+                    obj.type_.value,
+                    obj.docname,
+                    obj.anchor,
+                    obj.priority,
+                )
+
+    def clear_doc(self, docname: str) -> None:
+        for typ, objs in self.data.items():
+            if isinstance(typ, RustItemType):
+                self.data[typ][:] = [o for o in objs if o.docname != docname]
+
+    def _find_match(self, target: str, typ: str | None = None) -> Optional[RustItem]:
+        search_types = [RustItemType.from_str(typ)] if typ else self.data.keys()
+        matches = set()
+        for search_type in search_types:
+            matches.update(o for o in self.data[search_type] if o.name == target)
+        return list(matches)[0] if matches else None
+
+    def resolve_xref(
+        self,
+        env: BuildEnvironment,
+        fromdocname: str,
+        builder: Builder,
+        typ: str,
+        target: str,
+        node: pending_xref,
+        contnode: Element,
+    ) -> Element | None:
+        # pylint:disable=too-many-arguments
+        match = self._find_match(target, typ)
+        return (
+            make_refnode(
+                builder,
+                fromdocname,
+                match.docname,
+                (
+                    match.name.replace("::", "-")
+                    if match.type_ not in (RustItemType.MODULE, RustItemType.CRATE)
+                    else None
+                ),
+                [contnode],
+                match.name,
+            )
+            if match
+            else None
+        )
+
+    def resolve_any_xref(
+        self,
+        env: BuildEnvironment,
+        fromdocname: str,
+        builder: Builder,
+        target: str,
+        node: pending_xref,
+        contnode: Element,
+    ) -> list[tuple[str, Element]]:
+        # pylint:disable=too-many-arguments
+        match = self._find_match(target)
+        return (
+            make_refnode(
+                builder,
+                fromdocname,
+                match.docname,
+                (
+                    match.name.replace("::", "-")
+                    if match.type_ not in (RustItemType.MODULE, RustItemType.CRATE)
+                    else None
+                ),
+                [contnode],
+                match.name,
+            )
+            if match
+            else None
+        )
+
+    def merge_domaindata(self, docnames: list[str], otherdata: dict) -> None:
+        otherdata: dict[RustItemType, list[RustItem]]
+        for typ, objs in otherdata.items():
+            self.data[typ].extend(o for o in objs if o.docname in docnames)