sphinx-needs 9.0.0__tar.gz → 9.2.0__tar.gz

{sphinx_needs-9.0.0 → sphinx_needs-9.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sphinx-needs
-Version: 9.0.0
+Version: 9.2.0
 Summary: Sphinx needs extension for managing needs/requirements and specifications
 Author-email: team useblocks <info@useblocks.com>
 Requires-Python: >=3.11,<4
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Documentation
 Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
 Classifier: Framework :: Sphinx :: Extension
 License-File: AUTHORS
 License-File: LICENSE
@@ -29,7 +30,8 @@ Requires-Dist: sphinx-data-viewer~=0.1.5
 Requires-Dist: sphinxcontrib-jquery~=4.0
 Requires-Dist: typing-extensions>=4.14.0
 Requires-Dist: minijinja~=2.15
-Requires-Dist: ub-project>=1.1.0,<2
+Requires-Dist: ub-project>=1.2.0,<2
+Requires-Dist: ub-needs-exchange>=1.1.0,<2
 Requires-Dist: matplotlib>=3.3.0 ; extra == "docs"
 Requires-Dist: sphinxcontrib-plantuml~=0.0 ; extra == "docs"
 Requires-Dist: sphinx-copybutton~=0.5 ; extra == "docs"
@@ -37,6 +39,7 @@ Requires-Dist: sphinxcontrib-programoutput~=0.17 ; extra == "docs"
 Requires-Dist: sphinx-design~=0.6 ; extra == "docs"
 Requires-Dist: sphinx-ai-index>=1.0.0,<2 ; extra == "docs"
 Requires-Dist: sphinx-syntax-example~=0.2.0 ; extra == "docs"
+Requires-Dist: sphinxcontrib-mermaid>=1.0.0,<3 ; extra == "docs"
 Requires-Dist: matplotlib>=3.3.0 ; extra == "plotting"
 Requires-Dist: furo>=2025.12.19 ; extra == "theme-furo"
 Requires-Dist: sphinx-immaterial>=0.11.11,<0.14.0 ; extra == "theme-im"

sphinx_needs-9.2.0/docs/_static/_css/furo.css

@@ -0,0 +1,51 @@
+/* This site's own rules for the https://pradyunsg.me/furo theme. The useblocks look every
+   furo site in this repository shares is docs-theme/static/ub-furo.css, which loads before
+   this file; what is here is used by these docs alone. */
+
+/* the hero background on the landing page */
+body {
+    --sn-architecture-bg: url(../architecture_bg-light.png);
+}
+
+@media not print {
+    body[data-theme="dark"] {
+        --sn-architecture-bg: url(../architecture_bg-dark.png);
+    }
+
+    @media (prefers-color-scheme: dark) {
+        body:not([data-theme="light"]) {
+            --sn-architecture-bg: url(../architecture_bg-dark.png);
+        }
+    }
+}
+
+/** styling for the flowchart diagram on the landing page **/
+svg.sn-flow-chart path.text {
+    fill: var(--color-foreground-primary);
+}
+
+svg.sn-flow-chart rect.box {
+    stroke: var(--color-foreground-border);
+}
+
+svg.sn-flow-chart path.arrow {
+    fill: var(--ub-color-brand-main);
+}
+
+/** sphinx-design additional styling **/
+svg.fill-primary {
+    fill: var(--sd-color-primary);
+}
+
+/* the `dropdown` these docs redefine in conf.py (`sd_custom_directives`) */
+.sn-dropdown-default .sd-summary-icon svg {
+    color: var(--color-admonition-title--note);
+}
+
+.sn-dropdown-default {
+    border-left: .2rem solid var(--color-admonition-title--note) !important;
+}
+
+.sn-dropdown-default .sd-summary-title {
+    border-width: 0 !important;
+}

{sphinx_needs-9.0.0 → sphinx_needs-9.2.0}/docs/_static/ubc-theme.css

@@ -1,8 +1,9 @@
 /*
  * useblocks branding for the `ubc build html` site.
  *
- * The ubCode counterpart of `furo.css`, which brands the Sphinx build: same
- * identity, different engine. Wired up by `extra_css` in `docs/ubproject.toml`,
+ * The ubCode counterpart of `docs-theme/static/ub-furo.css` at the repository
+ * root (the look every furo site here shares, which brands the Sphinx build) and
+ * of this site's own `_css/furo.css`: same identity, different engine. Wired up by `extra_css` in `docs/ubproject.toml`,
  * and written entirely against the documented theming surface — the `--ubc-*`
  * custom properties and the `ub-*` class names
  * (docs/source/configuration/build_html.rst). Nothing here reaches into a rule
@@ -17,8 +18,9 @@
  * NOTE for the Sphinx side: this file sits under `html_static_path`, so
  * `sphinx-build` copies it into its own `_static/` — but it is deliberately
  * ABSENT from `html_css_files` in `docs/conf.py`. Sphinx is branded by
- * `furo.css`; linking this one there too would apply two theme layers to one
- * page. Leave it unlinked.
+ * `ub-furo.css` (added by the `ub_docs_theme` extension) and `_css/furo.css`;
+ * linking this one there too would apply two theme layers to one page. Leave it
+ * unlinked.
  */
 
 :root {

sphinx_needs-9.2.0/docs/api.rst

@@ -0,0 +1,462 @@
+.. _api:
+
+Python API
+==========
+
+**Sphinx-Needs** provides an open API for other Sphinx-extensions to provide specific need-types, create needs or
+make usage of the filter possibilities.
+
+The API allows the injection of extra configuration, but
+does not support manipulation of it (e.g remove need types),
+to keep the final configuration transparent for the Sphinx project authors.
+
+.. _api_public:
+
+What is public
+--------------
+
+A project or an extension may rely on the documented surface of Sphinx-Needs: its
+configuration, its directives and their options, the filter names (``c.*`` included), the
+``needs.json`` format, and the Python API this page documents (``create_need``,
+``resolve_need_option`` and reading the configuration through ``NeedsSphinxConfig`` among
+it). A name in it -- a configuration key, a directive or an option, a filter name, a
+``needs.json`` key, a documented function, class, argument or attribute -- is renamed or
+removed only after a deprecation: a ``needs.deprecated`` Sphinx warning (which
+``suppress_warnings`` silences) or a Python ``DeprecationWarning``, naming the replacement;
+the old spelling is removed only in a major release. What a name does is not frozen: a minor
+release may fix what it outputs, or report with a new warning what it accepted in silence,
+and the changelog says what changed and what to do.
+
+What this page labels **provisional** follows its label. Through 9.x that is the hop types
+and ``NeedItemSource``'s general constructor with its keywords: a minor release may add an
+optional field, a hop kind or a keyword, while a rename, a removal, or a change to the
+meaning or type of an existing one waits for 10.0, because published sibling extensions
+construct them. They stay outside the stable surface until ``needs.json`` carries them.
+
+Anything else is internal, and may change in a minor release without a deprecation: a name
+this page does not document, a module or a name starting with ``_``, and whatever is reached
+through one. The extensions developed in the Sphinx-Needs repository are changed with it in
+the same pull request, and released with a raised minimum version of Sphinx-Needs; an older
+release of one of them may need upgrading together with Sphinx-Needs. New internal modules
+start with ``_``, and public names live in, or are re-exported from, a public module with
+``__all__``; existing modules are not renamed wholesale.
+
+.. _`api_configuration`:
+
+Configuration
+-------------
+
+.. automodule:: sphinx_needs.api.configuration
+   :members:
+
+.. _api_reading_configuration:
+
+Reading the configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. py:currentmodule:: sphinx_needs.config
+
+.. py:class:: NeedsSphinxConfig(config)
+
+   The project's Sphinx-Needs configuration, for an extension to read:
+   ``NeedsSphinxConfig(app.config).<name>`` is the configuration value ``needs_<name>`` as
+   resolved, with :ref:`needs_from_toml` applied, and for ``types``, ``layouts``,
+   ``functions`` and ``warnings`` with what extensions and the configured services add
+   included. Read it from a ``builder-inited`` handler or later; in ``config-inited``, from
+   a handler at a priority above 600, once sphinx-needs has merged its defaults and compiled
+   the card layouts (``types`` alone is complete from a priority above 12). What an
+   extension adds is included once the extension has added it.
+
+   .. code-block:: python
+
+      from sphinx_needs.config import NeedsSphinxConfig
+
+      need_types = {t["directive"]: t for t in NeedsSphinxConfig(app.config).types}
+
+   Every attribute named after a Sphinx-Needs configuration value (:ref:`config`),
+   without the ``needs_`` prefix, is stable to read; ``functions`` gives the dynamic
+   functions by name, a mapping, where ``needs_functions`` is a list. Reading only: setting
+   a value through it is not supported. Its other members are internal, but one:
+
+   .. py:attribute:: variant_data_proxy
+
+      The ``var`` proxy that filters read over the variant data (``needs_variant_data``,
+      merged with its file), or ``None`` when there is none. Read-only.
+
+.. py:currentmodule:: None
+
+.. autoclass:: sphinx_needs.functions.functions.DynamicFunction
+   :members: __name__,__call__
+
+.. autoclass:: sphinx_needs.functions.functions.Reads
+
+Need
+----
+
+.. autofunction:: sphinx_needs.api.need.create_need
+
+.. automodule:: sphinx_needs.api.need
+   :members:
+   :exclude-members: create_need
+
+.. _api_migrating_add_need:
+
+Migrating from ``add_need``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 9.2.0
+
+   :func:`~sphinx_needs.api.need.add_need` is deprecated, and is removed in 10.0. Each
+   call is one Python ``DeprecationWarning`` at the calling line (not a Sphinx warning, so
+   a ``-W`` build of a project using an extension that still calls it is not failed by
+   it).
+
+:func:`~sphinx_needs.api.need.create_need` takes the need's location as one
+:class:`~sphinx_needs.need_item.NeedItemSource`, and its field values and links as two
+mappings, kept apart from its own arguments, so no name a project gives a field meets one
+of them. In a directive the source is ``NeedItemSource.from_directive(self)``:
+
+.. code-block:: python
+
+   # before
+   from sphinx.util.docutils import SphinxDirective
+
+   from sphinx_needs.api import add_need
+
+
+   class ReqDirective(SphinxDirective):
+       def run(self):
+           return add_need(
+               self.env.app, self.state, self.env.docname, self.lineno,
+               "req", self.arguments[0],
+               id=self.options.get("id"), status="open", priority="high", links="REQ_0",
+           )
+
+.. code-block:: python
+
+   # after
+   from sphinx.util.docutils import SphinxDirective
+
+   from sphinx_needs.api import NeedItemSource, create_need
+
+
+   class ReqDirective(SphinxDirective):
+       def run(self):
+           need, nodes = create_need(
+               self.env.app, self.state, NeedItemSource.from_directive(self),
+               "req", self.arguments[0],
+               id=self.options.get("id"),
+               fields={"status": "open", "priority": "high"},
+               links={"links": "REQ_0"},
+           )
+           return nodes
+
+``from_directive`` works for any docutils ``Directive``, not only a ``SphinxDirective``.
+With it, ``need["lineno"]`` is the line the directive is written on, which differs from
+``self.lineno`` where ``rst_prolog``, an include or generated input shifts the parser's
+count; to keep the old number exactly, use
+``NeedItemSource.on_page(self.env.docname, lineno=self.lineno)``, which is the source
+``add_need`` built. ``on_page`` gives the need its page and the line the caller passes,
+nothing more, so it is the source wherever the caller chooses the line: the directive's own
+parser line, as ``add_need`` took it, or the lines a directive's data names. It works in a docutils
+``Directive`` and in a nested parse alike, and is also the ``need_source`` to give
+``generate_need``; ``create_need`` records the page's file on its hop, ``generate_need``,
+which has no application, does not.
+``from_directive`` and ``on_page`` are stable, as the class's name is; the hops they build,
+and ``NeedItemSource``'s general constructor with its keywords (``hops``, ``lineno``,
+``lineno_content``, ``parser_lineno``, ``is_import``), are provisional until needs.json
+carries them: through 9.x a minor release only adds to them, and a rename or a removal
+waits for 10.0 (see :ref:`api_public`, and the provisional note under "Data", below). The
+constructor is for sphinx-needs' own producers and advanced use. ``create_need`` takes a
+``NeedItemSource`` and nothing else: an object with the ``NeedItemSourceProtocol``
+interface alone is refused with a ``TypeError``.
+
+A need placed on a page is created with a parser state, through ``create_need`` as through
+``add_need``: an event handler or a role, which has none, cannot create one, and without a
+state only an external need can be created (``add_external_need``). Where ``add_need``
+refused that with an ``AssertionError``, ``create_need`` raises ``ValueError``.
+
+.. deprecated:: 9.2.0
+
+   A ``need_source`` that is not a ``NeedItemSource`` -- an object with the
+   ``NeedItemSourceProtocol`` interface alone -- given to
+   :func:`~sphinx_needs.api.need.generate_need`,
+   :func:`~sphinx_needs.api.need.add_external_need` or
+   :func:`~sphinx_needs.api.need.ingest_need_record` is one Python ``DeprecationWarning``
+   at the calling line, and the need is created as before; it is refused from 10.0, as
+   ``create_need`` refuses it now. ``add_need`` gives no second warning for it.
+
+``add_need``'s other arguments:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 60
+
+   * - ``add_need``
+     - ``create_need``
+   * - ``docname``, ``lineno``
+     - ``source=NeedItemSource.from_directive(self)``; for a line the caller gives
+       (``add_need``'s ``self.lineno``), ``NeedItemSource.on_page(docname, lineno=lineno)``
+   * - ``lineno_content``
+     - ``from_directive`` sets it (the provisional constructor takes ``lineno_content=``)
+   * - ``need_source``
+     - ``source``, a ``NeedItemSource`` (an object with the ``NeedItemSourceProtocol``
+       interface alone, which ``add_need`` took, is refused)
+   * - ``status``, ``tags``, ``constraints``, ``hide``, ``collapse``, ``style``,
+       ``layout``, ``template``, ``pre_template``, ``post_template``, and every field
+     - ``fields={...}``
+   * - every link type
+     - ``links={...}``
+   * - ``id``, ``content``, ``doctype``, ``jinja_content``, ``full_title``,
+       ``allow_type_coercion``
+     - the same keyword
+   * - ``is_external``, ``external_url``, ``external_css``
+     - :func:`~sphinx_needs.api.need.add_external_need`, which is not deprecated (an
+       ``external`` hop as ``create_need``'s source, with ``state=None``, is the
+       provisional hop type, and takes no ``external_css``)
+   * - ``is_import``
+     - ``NeedItemSource(..., is_import=True)`` (the provisional constructor), or
+       :func:`~sphinx_needs.api.need.ingest_need_record` for a needs.json-style record
+   * - ``parts``, ``arch``, ``sections``, ``signature``
+     - none: for a need on the page they are computed from its content and the page (a
+       record's ``parts`` and ``arch`` through
+       :func:`~sphinx_needs.api.need.ingest_need_record`); an external need ``add_need``
+       made kept them as given, which neither ``create_need`` nor ``add_external_need``
+       takes
+   * - the deprecated ``links_string``, ``hide_tags``, ``hide_status``, ``delete``,
+       ``constraints_passed``
+     - none (``add_need`` drops them, with a warning)
+   * - the return value, ``list[nodes.Node]``
+     - ``(need, nodes)``: the need as recorded, and the nodes
+
+The five source classes of 9.1.0, ``NeedItemSourceUnknown``, ``NeedItemSourceDirective``,
+``NeedItemSourceService``, ``NeedItemSourceExternal`` and ``NeedItemSourceImport``, are
+deprecated names of :mod:`sphinx_needs.need_item` until 10.0: each is a function taking its
+class's keywords and returning the ``NeedItemSource`` with the legacy keys that class gave,
+and reading one is a ``DeprecationWarning``. ``NeedItemSourceUnknown(docname=docname,
+lineno=lineno)`` is ``NeedItemSource.on_page(docname, lineno=lineno)``.
+
+.. _api_content_markup:
+
+Content written in another markup
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An extension that creates needs whose text was written somewhere else -- a comment in a
+source file, an imported file -- in a markup that is not the page's passes
+``MarkupContent(text, markup=..., source=...)`` as the ``content`` of
+:func:`~sphinx_needs.api.need.create_need` (:func:`~sphinx_needs.api.need.add_need` takes
+the same ``content``). ``markup`` is the source suffix of that markup
+(``".rst"``, ``".md"``, or any suffix ``source_suffix`` maps to a reStructuredText or MyST
+parser): the content is parsed by that parser, whatever the page's parser, and the need
+records the suffix as its ``doctype``. With ``source=(path, first_line)``, the warnings
+raised while parsing the content, and those for references in it that do not resolve,
+name ``path`` and the line the content came from rather than the page -- through
+``sphinx.util.docutils.switch_source_input``, the same mechanism ``sphinx.ext.autodoc`` uses
+to report a docstring's lines at the Python file. ``create_need`` takes no other argument
+for this, and takes the fields and links as mappings, so no field or link name is reserved.
+:func:`~sphinx_needs.api.need.ingest_need_record` creates a need from a needs.json-style
+record, and is the path :ref:`needimport` itself takes for each need it imports; with
+:ref:`needs_import_parse_by_doctype` or its ``:parse_by_doctype:`` option set, needimport
+passes a record's ``doctype`` as the content's markup when the project parses it and the
+need is not rendered through a template.
+
+.. autoclass:: sphinx_needs.api.MarkupContent
+
+The content is parsed into the page it is rendered on, so a label defined in it belongs to
+that page and other pages reference it there. The warnings myst-parser logs itself, such as
+an unknown directive or role in Markdown content, name the page with the content's line;
+with myst-parser 4 their file is the content's path with ``.rst`` appended. In a
+reStructuredText page, MyST content's ``[text](#anchor)`` links are not resolved and a
+missing anchor is not reported; use the ``{ref}`` and ``{need}`` roles, which work in both.
+
+What such content should not contain
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This version parses the content as the page would parse it, and refuses none of the
+following; a later version will, as ubCode's reader already does:
+
+- directives that read files (``include``, ``literalinclude``, ``csv-table`` with
+  ``:file:``, ``raw`` with ``:file:``), and images and other references to files by a
+  relative path: Sphinx's ``include``, ``literalinclude`` and images, and everything in
+  MyST content, resolve against the page, while ``csv-table :file:`` and ``raw :file:``
+  in reStructuredText content resolve against the content's file;
+- ``raw``, and raw HTML in Markdown;
+- need or ``needimport`` directives: the needs they create are recorded against the page;
+- anything relying on the page's substitutions or ``rst_prolog``: it works, but the same
+  text means something else on another page.
+
+Events
+------
+
+**Sphinx-Needs** registers two Sphinx events, which an extension connects to with
+``app.connect(event_name, callback)``. Both are emitted once per build, in the main
+process (also in a parallel build), when the needs are first requested after all
+documents are read. Each callback is called as ``callback(app, needs)``, where ``needs``
+is the mutable mapping of need ids to needs, :py:obj:`~sphinx_needs.data.NeedsMutable`.
+
+``needs-before-post-processing``
+   Emitted before the ``needextend`` directives are applied and before dynamic
+   functions, links and constraints are resolved. This is the hook for an extension that
+   writes into the needs: a ``needextend`` in a document is applied afterwards, and can
+   override what the extension wrote.
+
+``needs-before-sealing``
+   Emitted after those steps, and before the needs become read-only. A callback sees
+   the needs as the ``needextend`` directives left them, with dynamic functions, links
+   and constraints resolved.
+
+.. code-block:: python
+
+   def default_status(app, needs):
+       for need in needs.values():
+           if need["type"] == "req" and not need["status"]:
+               need["status"] = "draft"
+
+   def setup(app):
+       app.connect("needs-before-post-processing", default_status)
+
+A field with a :ref:`derive <needs_derive>` rule cannot be set from a callback, a
+:ref:`filter function <filter_func>` or a :ref:`dynamic function <dynamic_functions>`: it holds
+what its rule computes, and ``need[name] = value`` raises ``KeyError``.
+
+
+Exceptions
+----------
+
+.. automodule:: sphinx_needs.exceptions
+   :members:
+
+Data
+----
+
+.. automodule:: sphinx_needs.need_item
+   :members: NeedItem, NeedLink, NeedPartItem, NeedItemSource, NeedItemSourceProtocol, NeedsContent, NeedPartData, NeedModification, NeedConstraintResults
+
+.. note::
+
+   **Stable**: ``NeedItemSource``'s name, ``NeedItemSource.from_directive`` and ``NeedItemSource.on_page``, and
+   reading a source through ``NeedItemSourceProtocol`` (``dict_repr``). **Provisional**: ``NeedItemSource``'s general
+   constructor and its keywords (``hops``, ``lineno``, ``lineno_content``, ``parser_lineno``, ``is_import``), the
+   stored legacy facts a later release turns into projections, for sphinx-needs' own producers and advanced use; and
+   the hops, below. Provisional means additions only through 9.x: a minor release may add an optional field, a hop
+   kind or a keyword, and a rename, a removal, or a change to an existing one's meaning or type waits for 10.0,
+   because published sibling extensions construct them (:ref:`api_public`).
+
+   **Provisional**: a :class:`~sphinx_needs.need_item.NeedItemSource` has ``hops``, where the need's text came from,
+   innermost first; the hop types, ``NeedSourceHop``, ``NeedSourcePhysical`` and ``NeedSourceSemantic``, are
+   importable from ``sphinx_needs.api``. The first hop is the innermost place sphinx-needs knows the need came through: for a need
+   directive or ``list2need``, the file the need is written in (an included file's own, in an include; the module,
+   for an autodoc docstring); for an imported need, the ``needs.json`` it was read from (where the exporting project
+   wrote the need is not a hop yet); for a service, the service that made it, then the file of the ``needservice``
+   directive; for an external need, its page on the other site, its only hop, with the need's sections there as its
+   semantic location, outermost first (the legacy ``sections`` keeps them innermost first). In a nested reStructuredText include,
+   the included file's hop is followed by one ``file`` hop per file it was included through, innermost first, each
+   with its path and suffix and no line, as docutils' ``include_log`` names them. Two known gaps: myst-parser's
+   ``{include}`` is never logged, so a chain through MyST includes records its reStructuredText links alone (a
+   reStructuredText include in ``eval-rst`` is logged, a MyST include around it is not), and under docutils 0.22 and
+   later a file included with ``:parser:`` is not logged (it is parsed into a document of its own), so it is no link
+   of a chain through it, and a need written in that file itself records no chain at all (docutils 0.21 logs it). A
+   need created
+   through ``add_need`` or ``NeedItemSource.on_page`` has its page alone, whose file ``create_need`` records with no line
+   (the line the caller gives is not checked in the file); ``generate_need`` has no application, so it records no
+   page path; and no hops without a document
+   (``NeedItemSource.from_directive`` records the directive's file and lines, as a need directive does). The last hop with a ``document`` is
+   the page the need is placed on (an external need has none), and carries its sections and the domain objects it
+   is written in, outermost first. A hop has a line
+   range only where the file, read from disk, holds the need's text there: in reStructuredText every line of the
+   directive equals the file's line (whole lines, after a block quote's or a table cell's border, and the bullets of
+   the list item the directive opens); in MyST the line opens the directive's fence with its name and title.
+   Elsewhere the hop has no line. A recorded line can still be wrong only where the file holds an identical copy of
+   the need's text at the line the parser claims: a MyST need nested at once inside an identical twin (same name, same
+   title). In reStructuredText, a need in an included slice (``:start-after:``, ``:start-line:``) records the line it
+   is written on in the file, as its ``lineno`` and on its file hop, although docutils' own messages about the same
+   text (an unknown role in its content, say) name the line counted from the slice's start. It keeps the slice's line
+   where the slice cannot be matched with the file (an ``include-read`` handler that rewrote it, a file decoded
+   otherwise than with the project's ``source_encoding``, a ``:parser:`` include), and for a need in a table cell, in
+   ``list2need`` item content, in content parsed in a declared markup, or generated by a ``test-report``. Every path
+   is POSIX and relative to its hop's root: the source directory (``"srcdir"``, with ``..`` for a file outside it),
+   or, where ``root`` is ``None``, the producer's own root, which this build does not know, the path as the producer
+   gives it (a test report's test file, relative to the test run's root). A hop's ``semantic`` is ``None`` where it is
+   not determined, or where nothing finer than the file is known. Until the shape reaches ``needs.json``, a 9.x minor
+   release only adds to it, as above; ``NeedItemSourceProtocol`` does not include it, so read it with
+   ``getattr(need.source, "hops", ())``. A filter reads it through the ``c.source`` facets (:ref:`filter_source`),
+   its stable view: each facet names a position in the hops (``c.source.path`` the innermost, ``c.source.paths`` every
+   one), and keeps its meaning when the hops change shape. Nothing a table or ``needs.json`` shows depends on it.
+
+   A hop's ``language`` is what its text is written in, by the kind of hop: for a ``page`` hop, the page's suffix
+   its parser keys on (``.rst``, ``.md``); for a ``file`` hop, the file's own suffix (``.rst``, ``.json``; an
+   included ``inc.rst.txt`` records ``.txt``, whichever parser reads it); for a ``code`` hop, the language's name
+   (``python``, ``cpp``, ...), as sphinx-codelinks records it, as the ``code`` hop of a docstring autodoc reads
+   records it (``python``), and as sphinx-test-reports names a test case's file by its suffix (none for a suffix it
+   does not know).
+
+   A semantic entry's ``kind`` is in the vocabulary of its hop's kind and producer: a ``page`` hop's entries use the
+   document's (``section``, ``<domain>:<objtype>``), an ``external`` hop's are the ``section`` entries of the other
+   site's page, a ``generated`` hop's name its generator (``service``), and a
+   ``code`` hop's use its producer's entity kinds, read with the hop's ``language``: sphinx-codelinks' bare ones
+   (``function``, ``method``, ``class``, ``impl``, ...). In a ``code`` hop the kinds may carry
+   identity the names alone do not (Python's ``<locals>`` boundary is implied by a function or method followed by
+   another entry), so code hops compare by their producer's identity rule, not entry by entry. The innermost entry
+   of a ``code`` hop, the entity, carries its qualified name in its file as the producer renders it, a
+   ``("qualified_name", ...)`` extra: sphinx-codelinks' analysis renders it by the language (``ns::Widget::draw``,
+   ``<Widget as Shape>::area``, ``Shape.area.<locals>.inner``), and autodoc's docstring hop renders a Python entity
+   as sphinx-codelinks does (``make.<locals>.Made.go``), except a name CPython NFKC-normalises (``file`` reads
+   ``file`` in autodoc's hop and as written in sphinx-codelinks'). It is the producer's rendering of the entries'
+   names, so it adds no identity, and identity comparisons (sphinx-codelinks' ``name_chain``) leave it out. The
+   entity's own line range is not recorded: it is not identity.
+
+   Autodoc's docstring hop uses the same Python kinds as sphinx-codelinks, read from the syntax of the file the
+   docstring is defined in: ``class``, ``method`` for a ``def`` directly in a class, ``function`` for any other
+   ``def``, with ``<locals>`` implied, so a method of a class made in a function is ``function make > class Made >
+   method go``. A ``property``, a ``staticmethod`` or a ``classmethod`` is a ``method``, an exception a ``class``:
+   the page hop keeps autodoc's object type (``py:property``). An attribute documented with ``#:`` is a leaf
+   ``attribute`` (``class Shape > attribute sides``), where sphinx-codelinks attaches the same comment to the
+   enclosing class, or to the file. Autodoc names a docstring by its object's module and qualified name; the name is
+   tried at each module it starts with, longest first, and the definition it resolves to is trusted only where its
+   docstring holds every line of the need. The file is then that definition's, so a member inherited from another
+   module records that module's file. A module docstring
+   records its file alone. Where no definition holds the text, the hop records the file autodoc gives and nothing
+   finer, never another entity: an alias (autodoc names it by the object it aliases), an override that inherits its
+   docstring, an object made at run time, a function with no Python source. A function whose ``__module__`` is
+   rewritten to another module records that module's file, which does not hold the text either: a known gap.
+
+.. autoclass:: sphinx_needs.api.NeedSourceHop
+   :members:
+
+.. autoclass:: sphinx_needs.api.NeedSourcePhysical
+   :members:
+
+.. autoclass:: sphinx_needs.api.NeedSourceSemantic
+   :members:
+
+.. automodule:: sphinx_needs.data
+   :members: NeedsInfoType, NeedsInfoComputedType, NeedsSourceInfoType, NeedsMutable, NeedsPartType
+
+Views
+-----
+
+These views are returned by certain functions, and injected into filters,
+but should not be instantiated directly.
+
+.. automodule:: sphinx_needs.views
+   :members:
+   :undoc-members:
+   :special-members: __iter__, __getitem__, __len__
+
+Schema
+------
+
+.. automodule:: sphinx_needs.needs_schema
+   :members: FieldsSchema, TypeFieldsSchema, FieldShape, LinkShape, FieldSchema,
+             FieldFunctionArray, LinksFunctionArray, FieldLiteralValue, LinkSchema,
+             LinkDisplayConfig, LinkTargetTypes, LinksLiteralValue, BackLinksSchema,
+             AllowedTypes, narrowing_problems
+
+.. automodule:: sphinx_needs.derive
+   :members: DeriveRule, DeriveJoin, DeriveInvalid, DeriveCall
+
+.. automodule:: sphinx_needs.schema.config
+   :members: FieldStringSchemaType, FieldBooleanSchemaType,
+             FieldIntegerSchemaType, FieldNumberSchemaType,
+             FieldMultiValueSchemaType,
+             LinkSchemaType, LinkItemSchemaType

{sphinx_needs-9.0.0 → sphinx_needs-9.2.0}/docs/builders.rst

@@ -47,6 +47,16 @@ As well as the ``needs`` data, each version in the **needs.json** file carries a
 This is a JSON schema for the data structure of a single need,
 and also includes a ``field_type`` for each field, to denote the source of the field,
 that can be one of: ``core``, ``links``, ``backlinks``, ``extra``.
+A field, core or extra, is written as the project declares it for all need types together (a need type's own declaration is not written),
+a :ref:`needs_fields` entry narrowing a core field included:
+its type (with ``null`` where it is nullable), its item type and its default, but not its other constraints, such as an ``enum``.
+A link type is written with its default links as a need holding them writes its links --
+sorted and deduplicated, each with its condition under :ref:`needs_json_include_link_conditions` (the default) and without it otherwise:
+the literal ``default`` of its :ref:`needs_links` entry
+(a default a dynamic function or a variant computes is written ``[]``, as is a derived link type's,
+but for one derived by type alone, whose default is the links of a need type without a rule).
+
+How a needs.json is read is specified once, in the `needs.json exchange contract <https://github.com/useblocks/sphinx-needs/blob/master/packages/ub-needs-exchange/design/exchange-contract.md>`__ of the ``ub-needs-exchange`` library, through which :ref:`needimport` and :ref:`needs_external_needs` read it (ubCode is to vendor the contract's conformance corpus, and to be held to it); :ref:`needs_file` still reads the file with Python's ``json`` module, and moves to the library with the writer.
 
 See also :ref:`needs_json_exclude_fields`, :ref:`needs_json_remove_defaults`, :ref:`needs_reproducible_json`, and :ref:`needs_json_include_link_conditions` for more options on modifying the content of the ``needs.json`` file.
 

{sphinx_needs-9.0.0 → sphinx_needs-9.2.0}/docs/card_layouts.rst

@@ -447,10 +447,9 @@ A header without a meta region leaves an empty band
    id in the normal reading direction.
 
 Layouts registered by services are not part of the collision set
-   Services register their layouts later in the build than card layouts are compiled, so a
-   card named after one of them — ``github``, for the :ref:`GitHub service <github_service>`
-   — takes precedence over it silently, exactly as a :ref:`needs_layouts` entry of that name
-   does today.
+   A layout a service registers is read after every configured layout, so a card named after
+   one of them — ``github``, for a configured :ref:`GitHub service <github_service>` — takes
+   precedence over it silently, exactly as a :ref:`needs_layouts` entry of that name does.
 
 Invalid specifications
 ----------------------