VHDLDomain

Summary

Doc-string:

documented

File	Expected	Covered	Uncovered	Coverage
__init__.py	35	34	1	97.1%
Overall (6 files)	157	154	3	98.1%

Modules

Module	Expected	Covered	Uncovered	Coverage
DesignUnit	42	41	1	97.6%
Directive	25	24	1	96.0%
Frontend	16	16	0	100.0%
Index	24	24	0	100.0%
Pages	15	15	0	100.0%

Source

VHDLDomain/__init__.pydocumentedundocumentedignoredexcludednot counted

"""
**A Sphinx domain providing VHDL language support.**

The domain ``vhdl`` documents VHDL designs from their model, a :class:`pyVHDLModel.Design`. The designs are declared
in :file:`conf.py` (see :mod:`VHDLDomain.Frontend`) and read when the builder is initialized; a directive describes a
design, a library or a design unit from the model, and a role refers to what a directive described.

.. code-block:: rst

   .. vhdl:design:: StopWatch

   .. vhdl:library:: lib_StopWatch

   The entity :vhdl:ent:`Counter` counts clock cycles.

.. rubric:: What it registers

* Directives: ``vhdl:design``, ``vhdl:library``, ``vhdl:context``, ``vhdl:entity``, ``vhdl:package``,
  ``vhdl:configuration``
* Roles: ``:vhdl:design:``, ``:vhdl:lib:``, ``:vhdl:ctx:``, ``:vhdl:ent:``, ``:vhdl:arch:``, ``:vhdl:pack:``,
  ``:vhdl:config:``, ``:vhdl:type:``, ``:vhdl:const:``, ``:vhdl:func:``, ``:vhdl:proc:``, ``:vhdl:generic:``,
  ``:vhdl:port:``
* Indices: ``vhdl-entities``, ``vhdl-packages``, ``vhdl-subprograms``, ``vhdl-types``
* Configuration value ``vhdl_designs``
* Generated pages per library and design unit, for a design declared with ``pages`` (see :mod:`VHDLDomain.Pages`)

.. rubric:: Names

An object's qualified name starts with its design and library, e.g. ``StopWatch.lib_StopWatch.Counter``; a reference
names it by the qualified name, or by a part of it ending with the object's name, e.g. ``lib_StopWatch.Counter`` or
``Counter``. A subprogram's name may end in its signature, the type marks of its parameters, e.g.
``Utilities.to_index(natural, positive)``. A name matching several objects - also a subprogram's overloads without a
signature - is resolved in the design and library of the last ``vhdl:design`` and ``vhdl:library`` before the
reference, otherwise it is warned about. VHDL identifiers are case-insensitive, so are the names.

.. admonition:: Copyright Information

   :copyright: Copyright 2017-2026 Patrick Lehmann - Bötzingen, Germany
   :copyright: Copyright 2016-2017 Patrick Lehmann - Dresden, Germany
   :license: Apache License, Version 2.0
"""
...

__author__ =    "Patrick Lehmann"
__email__ =     "Paebbels@gmail.com"
__copyright__ = "2016-2026, Patrick Lehmann"
__license__ =   "Apache License, Version 2.0"
__version__ =   "0.2.0rc1"

...

__all__ = ["OBJECT_TYPES", "ROLES"]

_logger = getLogger(__name__)

#: The object types: their display names, by object type.
OBJECT_TYPES: dict[str, str] = {
	"design":        "design",
	"library":       "library",
	"context":       "context",
	"entity":        "entity",
	"architecture":  "architecture",
	"package":       "package",
	"configuration": "configuration",
	"type":          "type",
	"subtype":       "subtype",
	"constant":      "constant",
	"function":      "function",
	"procedure":     "procedure",
	"generic":       "generic",
	"port":          "port",
}

#: The roles: the object types each refers to, by role name.
ROLES: dict[str, tuple[str, ...]] = {
	"design":  ("design", ),
	"lib":     ("library", ),
	"ctx":     ("context", ),
	"ent":     ("entity", ),
	"arch":    ("architecture", ),
	"pack":    ("package", ),
	"config":  ("configuration", ),
	"type":    ("type", "subtype"),
	"const":   ("constant", ),
	"func":    ("function", ),
	"proc":    ("procedure", ),
	"generic": ("generic", ),
	"port":    ("port", ),
}

@export
def normalizeName(name: str) -> str:
	"""
	Normalize an object's name for comparison: lower case, without white space.

	VHDL identifiers are case-insensitive; white space may separate the type marks of a subprogram's signature.

	:param name: The name.
	:returns:    The normalized name.
	"""
	...

@export
class VHDLXRefRole(XRefRole):
	"""
	A role of domain ``vhdl``, referring to an object a directive described.

	The reference remembers the design and library current where it is written - set by ``vhdl:design`` and
	``vhdl:library`` -, so an ambiguous name is resolved in them. A leading ``~`` shows only the object's name, the last
	part of the target.
	"""

	def process_link(
		self,
		env:                BuildEnvironment,
		refnode:            Element,
		has_explicit_title: bool,
		title:              str,
		target:             str
	) -> tuple[str, str]:
		"""
		Remember the current design and library on the reference, and shorten the title for a leading ``~``.

		:param env:                The build environment.
		:param refnode:            The reference node.
		:param has_explicit_title: ``True``, if the role was written with a title, as ``text <target>``.
		:param title:              The title.
		:param target:             The target.
		:returns:                  The title and the target.
		"""
		...

@export
class VHDLDomain(Domain):
	"""
	The Sphinx domain ``vhdl``, documenting VHDL designs from their model.

	Its objects are keyed by object type and normalized qualified name - ``("entity", "stopwatch.lib_stopwatch.counter")``
	- and located by document and anchor. The designs are no domain data, as the environment pickles the data: they are
	read again by every build, and handed to the domain by :meth:`AddDesign`.
	"""

	name =         "vhdl"  #: Name of the domain, the prefix of its directives and roles.
	label =        "VHDL"  #: Name of the domain, as displayed.
	data_version = 1       #: Version of the data layout; a change discards pickled environments.

	object_types: ClassVar[dict[str, ObjType]] = {
		objectType: ObjType(displayName, *[roleName for roleName, types in ROLES.items() if objectType in types])
		for objectType, displayName in OBJECT_TYPES.items()
	}  #: The object types, each with the roles referring to it.

	directives: ClassVar[dict[str, type]] = {
		"design":        DesignDirective,
		"library":       LibraryDirective,
		"context":       ContextDirective,
		"entity":        EntityDirective,
		"package":       PackageDirective,
		"configuration": ConfigurationDirective,
	}  #: The directives, by name.

	roles: ClassVar[dict[str, XRefRole]] = {  # type: ignore[assignment]
		roleName: VHDLXRefRole(innernodeclass=nodes.literal, warn_dangling=True) for roleName in ROLES
	}  #: The roles, by name.

	indices: ClassVar[list[type[Index]]] = [
		EntityIndex,
		PackageIndex,
		SubprogramIndex,
		TypeIndex,
	]  #: The indices, each a page ``vhdl-<name>``, e.g. ``vhdl-entities``.

	dangling_warnings: ClassVar[dict[str, str]] = {
		roleName: f"VHDL {' or '.join(OBJECT_TYPES[objectType] for objectType in types)} '%(target)s' not found"
		for roleName, types in ROLES.items()
	}  #: The warning for a reference to an undocumented object, per role.

	initial_data: ClassVar[dict[str, Any]] = {
		"objects": {},
	}  #: The domain's data: ``objects`` maps (object type, normalized name) to (document, anchor, qualified name).

	#: The configuration values the domain adds to :file:`conf.py`, as ``name: (default, rebuild, types)``. Each is
	#: registered with the domain's name as prefix, e.g. ``vhdl_designs``.
	#:
	#: ``designs``
	#:    The designs to read, by name: the directory of the source files and the libraries' files, see
	#:    :mod:`VHDLDomain.Frontend`.
	configValues: ClassVar[dict[str, tuple[Any, str, Any]]] = {
		"designs": ({}, "env", dict),
	}

	_designs: dict[str, Design]                                     #: The designs read by this build, by name.
	_lookup:  Nullable[dict[tuple[str, str], list[tuple[str, str]]]]  #: Object keys by (object type, last name part).

	def __init__(self, env: BuildEnvironment) -> None:
		"""
		Initializes the domain.

		:param env: The build environment.
		"""
		...

	@readonly
	def Objects(self) -> dict[tuple[str, str], tuple[str, str, str]]:
		"""
		Read-only property to return the documented objects.

		:returns: A mapping of (object type, normalized qualified name) to (document, anchor, qualified name).
		"""
		...

	@readonly
	def Designs(self) -> dict[str, Design]:
		"""
		Read-only property to access the designs read by this build (:attr:`_designs`).

		:returns: Dictionary of the designs, indexed by design name.
		"""
		...

	def AddDesign(self, name: str, design: Design, pages: Nullable[str] = None, source: Nullable[Path] = None) -> None:
		"""
		Add a design, which the directives can describe, and generate its pages.

		Besides the designs of ``vhdl_designs``, a design read by another frontend can be added, by a handler of Sphinx'
		``builder-inited`` event in :file:`conf.py`.

		:param name:                 The design's name, as directives and roles name it.
		:param design:               The design.
		:param pages:                Optional, document name the design's pages are generated below. Default: ``None``,
		                             no pages.
		:param source:               Optional, the file or directory Sphinx regards as the pages' source. Default:
		                             ``None``, the Sphinx source directory.
		:raises ValueError:          If parameter 'name' is ``None`` or empty.
		:raises TypeError:           If parameter 'name' is not of type :class:`str`.
		:raises ValueError:          If parameter 'design' is ``None``.
		:raises TypeError:           If parameter 'design' is not of type :class:`~pyVHDLModel.Design`.
		:raises VHDLDomainException: If a design of that name was added already.
		"""
		...

	def GetDesign(self, name: str) -> Nullable[Design]:
		"""
		Return a design by name.

		:param name: The design's name; case-insensitive.
		:returns:    The design, or ``None`` if no design of that name was added.
		"""
		...

	def NoteObject(self, objectType: str, qualifiedName: str, nodeID: str, location: Nullable[Node] = None) -> None:
		"""
		Register a documented object.

		An object described twice - e.g. by two directives - is warned about; the later description wins.

		:param objectType:    The object type, as ``entity``.
		:param qualifiedName: The object's qualified name, as ``StopWatch.lib_StopWatch.Counter``.
		:param nodeID:        The anchor of the object's node.
		:param location:      Optional, the node a duplicate is reported at. Default: ``None``.
		:raises ValueError:   If parameter 'objectType' is not an object type of the domain.
		"""
		...

	def FindObjects(
		self,
		objectTypes: Iterable[str],
		target:      str,
		design:      Nullable[str] = None,
		library:     Nullable[str] = None
	) -> list[tuple[str, str]]:
		"""
		Find the objects a reference's target names.

		The target names an object by its qualified name or by a part of it ending with the object's name; it may end
		in a subprogram's signature, which must match then: the same number of type marks, each a type mark of the
		object's signature or a part of it ending with the type's name (``unsigned`` matches ``ieee.numeric_std.unsigned``).
		A qualified name equal to the target wins over the others. Of several matches, those in the given design - and
		then those in the given library - win.

		:param objectTypes: The object types the reference's role refers to.
		:param target:      The reference's target.
		:param design:      Optional, the design current at the reference. Default: ``None``.
		:param library:     Optional, the library current at the reference. Default: ``None``.
		:returns:           The keys of the matching objects: none, one, or several if the name is ambiguous.
		"""
		def signatureMatches(objectSignature: str, targetSignature: str) -> bool:
			"""
			Nested function checking whether a target's signature names an object's signature, type mark by type mark.

			:param objectSignature: The object's normalized signature, without the opening parenthesis.
			:param targetSignature: The target's normalized signature, without the opening parenthesis.
			:returns:               ``True``, if every type mark of the target names the object's type mark at its position.
			"""
			...

		...

	def clear_doc(self, docname: str) -> None:
		"""
		Remove the objects of a document, before it is read again.

		:param docname: The document.
		"""
		...

	def merge_domaindata(self, docnames: Iterable[str], otherdata: dict[str, Any]) -> None:
		"""
		Merge the objects a parallel reader collected for its documents.

		:param docnames:  The documents the other reader read.
		:param otherdata: The other reader's data.
		"""
		...

	def resolve_xref(
		self,
		env:         BuildEnvironment,
		fromdocname: str,
		builder:     Builder,
		typ:         str,
		target:      str,
		node:        addnodes.pending_xref,
		contnode:    Element
	) -> Nullable[Element]:
		"""
		Resolve a reference by one of the domain's roles.

		:param env:         The build environment.
		:param fromdocname: The document containing the reference.
		:param builder:     The builder.
		:param typ:         The role's name, as ``ent``.
		:param target:      The target, as ``lib_StopWatch.Counter``.
		:param node:        The pending reference.
		:param contnode:    The node rendering the reference's title.
		:returns:           The reference, the title if the name is ambiguous, or ``None`` if the target isn't documented.
		"""
		...

	def resolve_any_xref(
		self,
		env:         BuildEnvironment,
		fromdocname: str,
		builder:     Builder,
		target:      str,
		node:        addnodes.pending_xref,
		contnode:    Element
	) -> list[tuple[str, nodes.reference]]:
		"""
		Resolve a reference by the ``:any:`` role, trying every role with an unambiguous match.

		:param env:         The build environment.
		:param fromdocname: The document containing the reference.
		:param builder:     The builder.
		:param target:      The target.
		:param node:        The pending reference.
		:param contnode:    The node rendering the reference's title.
		:returns:           A pair of role and reference per role the target resolves for.
		"""
		...

	def get_objects(self) -> Iterator[tuple[str, str, str, str, str, int]]:
		"""
		Iterate the documented objects, for the search index and the inventory.

		:returns: An iterator of (name, display name, type, document, anchor, priority).
		"""
		...

@export
def readDesigns(sphinx: Sphinx) -> None:
	"""
	Call-back for Sphinx' ``builder-inited`` event, reading the designs of ``vhdl_designs`` into the domain.

	A design, which can't be read, is logged as an error rather than stopping the build; a directive describing it warns
	on its own.

	:param sphinx: The Sphinx application.
	"""
	...

@export
def setup(sphinx: Sphinx) -> dict[str, Any]:
	"""
	Register the domain ``vhdl`` and its configuration values with Sphinx.

	:param sphinx: The Sphinx application to register with.
	:returns:      The extension's metadata.
	"""
	...