Directive

Summary

Package:

VHDLDomain

Doc-string:

documented

File	Expected	Covered	Uncovered	Coverage
Directive.py	25	24	1	96.0%

Source

VHDLDomain/Directive.pydocumentedundocumentedignoredexcludednot counted

"""
The directives of the domain ``vhdl``: each describes an object of a design read into the domain.

``vhdl:design`` and ``vhdl:library`` set the design and library the following directives and references of the
document are in, until the next one.
"""
...

_logger = getLogger(__name__)

@export
class VHDLDirective(SphinxDirective):
	"""
	Base-class of the directives of domain ``vhdl``: access to the domain, the current design and library, and the
	registration of a described object.
	"""

	_WARNING_TYPE: ClassVar[str] = "vhdl"  #: Type of the warnings the directives emit, the domain's name.

	directiveName: ClassVar[str]  #: Name the directive is invoked by, used in every warning.

	def _Domain(self) -> VHDLDomain:
		"""
		Return the domain ``vhdl``.

		:returns: The domain.
		"""
		...

	def _CurrentDesign(self) -> tuple[Nullable[str], Nullable[Design]]:
		"""
		Return the design the directive is in: the one of option ``:design:``, else the current one.

		A missing design is warned about.

		:returns: The design's name and the design, or ``None`` and ``None`` if no design is current, or the name and
		          ``None`` if the design wasn't read.
		"""
		...

	def _NodeID(self, objectType: str, qualifiedName: str) -> str:
		"""
		Return the anchor of a described object, unique in the document.

		The anchor is built from the object type and the lower-case qualified name, e.g.
		``vhdl-entity-stopwatch.lib_stopwatch.counter``.

		:param objectType:    The object type, as ``entity``.
		:param qualifiedName: The object's qualified name, as ``StopWatch.lib_StopWatch.Counter``.
		:returns:             The anchor, from the lower-case qualified name.
		"""
		...

	def _Target(self, objectType: str, qualifiedName: str, indexText: str) -> list[Node]:
		"""
		Create the target and the index entry of a described object, and register it in the domain.

		:param objectType:    The object type, as ``entity``.
		:param qualifiedName: The object's qualified name, as ``StopWatch.lib_StopWatch.Counter``.
		:param indexText:     The text of the object's entry in the general index.
		:returns:             The index node and the target node.
		"""
		...

	def _Documentation(self, documentation: Nullable[str]) -> list[Node]:
		"""
		Parse an object's documentation comment as reStructuredText.

		A line's leading comment marker ``--`` and the space following it are removed, so a comment block reads as text.

		:param documentation: The documentation comment, as the frontend extracted it, or ``None``.
		:returns:             The parsed nodes, none for no or an empty comment.
		"""
		...

	def _Format(self, element: object) -> str:
		"""
		Write a model element - a symbol, an expression - as VHDL source text.

		An element the writer of pyVHDLModel can't write yet is written by its name, if it has one, and warned about.

		:param element: The model element.
		:returns:       The VHDL source text.
		"""
		...

@export
class DesignDirective(VHDLDirective):
	"""
	The directive ``vhdl:design``: a design's target and index entry, and the current design of the document.

	.. code-block:: rst

	   .. vhdl:design:: StopWatch

	The argument is the design's name, a key of ``vhdl_designs``. Every directive and reference following it in the
	document is in this design. The directive writes no visible output except its content; placed above a page's title,
	its target is the title, as a label is. With ``:no-index:``, it only makes the design the current one - for the
	other pages of a design.

	A design with generated pages (key ``pages`` in ``vhdl_designs``) lists its library pages in a hidden table of
	contents, so they are below the directive's document in the navigation.
	"""

	directiveName: ClassVar[str] = "vhdl:design"  #: Name the directive is invoked by.

	has_content =        True                            #: The content describes the design.
	required_arguments = 1                               #: The design's name.
	option_spec =        {"no-index": directives.flag}   #: Make the design current, without a target and index entry.

	def run(self) -> list[Node]:
		"""
		Register the design, make it the current one, and parse the content.

		:returns: An index node, the design's target and the content's nodes.
		"""
		...

@export
class LibraryDirective(VHDLDirective):
	"""
	The directive ``vhdl:library``: a library's target, index entry and design units, and the current library of the
	document.

	.. code-block:: rst

	   .. vhdl:library:: lib_StopWatch
	      :design: StopWatch

	The argument is the library's name; without ``:design:``, the library is in the current design. Every directive and
	reference following it in the document is in this library. The directive writes the library's documentation, its
	content, and a table of the library's design units - each name referring to the unit's description, if there is
	one. With ``:no-index:``, it only makes the library the current one, and writes nothing.
	"""

	directiveName: ClassVar[str] = "vhdl:library"  #: Name the directive is invoked by.

	has_content =        True  #: The content describes the library.
	required_arguments = 1     #: The library's name.
	option_spec =        {
		"design":   directives.unchanged_required,
		"no-index": directives.flag,
	}  #: The design, if not the current one; ``:no-index:`` makes the library current, without describing it.

	#: The kinds of design units the table lists, with the collection of :class:`~pyVHDLModel.Library` and the role.
	_UNIT_KINDS: ClassVar[tuple[tuple[str, str, str], ...]] = (
		("Context",       "Contexts",       "ctx"),
		("Entity",        "Entities",       "ent"),
		("Package",       "Packages",       "pack"),
		("Configuration", "Configurations", "config"),
	)

	def run(self) -> list[Node]:
		"""
		Register the library, make it the current one, and write its documentation, content and design units.

		:returns: An index node, the library's target, and the library's description.
		"""
		...

	def _DesignUnits(self, library: Library) -> Nullable[nodes.table]:
		"""
		Create the table of a library's design units: kind and name, the name referring to the unit's description.

		:param library: The library.
		:returns:       The table, or ``None`` if the library has no design units.
		"""
		...