there are situations where you want to enforce that a vertex has certain links. For example you may wish to enforce that system requirement is traceable to at least one user requirement, and fails validation if it doesn't.

I would image adding require_parent and require_child config options.
I would also add a way to apply this config to whole swathes of vertices, without having to manually specify it in each one.

the 'fingerprints' used to track changes to parent tasks are currently an alphanumeric md5 hash, truncated to 4 digits. That's probably excessive. 3 or even 2 digits is plenty, as hash collisions are unlikely (only 2 values to collide) and not thaaat critical if they do.

There are 62 alphanumeric characters, so with 2 characters the odds of collision are

1 - P(2 different numbers)
1 - (1 * 61/62)
~0.016

with 3 characters the odds are
(1 - (1 * (62^2-1) / 62^2)
~0.00026, or about 3 in 10 000

I'll leave it for now, but it's easier to change or even make configurable

add a traceability matrix feature.

A traceability matrix is used to show links and coverage from parents to children. For example, to show the links and coverage between requirements and their associated test cases.

For use in this library, this can be a bit more generic.

• both 'parents' and 'children' can be the result of arbitrary queries
• a 'link' need not be direct, so a link would show whether or not one node was an ancestor/descendent of another (ie. separated by multiple 'generations')
• it's an error for one of the nodes in the 'parent' query to be a descendent of one of the nodes in the 'child' query (and vice versa)

so i'm imagining a directive like the following-

.. vertex-matrix::
    :parents: parent-query
    :children: child-query

    [parents]
    key1 = value1
   
    [children] 
    key2 = value2
    key3 = value3

where the query names are defined in the config, and key-value pairs can be injected using toml in the body of the directive.

In practice you'd have a default query with some sensible kwargs, so you'd have something like

.. vertex-matrix::

    [parents]
    type = "USR"
   
    [children] 
    type = "SYS"

or, equivalently-

.. vertex-matrix::

    parents = { type = "USR" }  
    children = { type = "SYS" }

this would output a table vaguely like the following -

with the results of each query being the row and column headers, and the value of each cell being determined by the relationship between the two corresponding nodes.

the PDF output of the docs/ directory doesn't currently build. Need to figure out why, fix it, and test it in CI to ensure it doesn't get broken again

a docs/ repo intended to be built on read-the-docs is added in #28

for reasons that are not clear to me, the build is failing.

See:

• readthedocs/readthedocs.org#9626
• sphinx-doc/sphinx#10836

there are three options here

1. add a 'see also' type feature where you can manually link related vertices and show links between them
2. show links to literal graph 'siblings'
3. both of the above

1. can be solved manually using normal sphinx reference tools. not sure if 2. is useful. I'll leave this on the backlog unless someone can articulate a use-case to me

update the readme

• better description of project goals and use-cases
• reference (deference) to sphinx-needs, the full-featured granddaddy of this project

also add a 'docs' repo to start storing proper documentation of this repo and it's features. Probably using sphinx 'autodoc'.

allow nodes to be completely transparent in the built docs.

For example, so that a paragraph in a market requirements document can be treated as a 'requirement', but without breaking the flow of the document.

Glossary terms nested inside vertices don't work. It's most obvious when using the latexpdf builder (seems to just fail silently when building html)

Exception occurred:
  File "/home/daniel.eades/Code/python/sphinx-graph/.venv/lib/python3.10/site-packages/docutils/nodes.py", line 652, in __getitem__
    return self.attributes[key]
KeyError: 'refdocname'

the layouts all work, and build in both html and PDF, however there's plenty of room for improvement

'scoped tags' is a concept borrowed from gitlab.

scoped tags are a special type of tag, where each 'variant' of a single tag scope is mutually exclusive. That is, a vertex may only have one tag in a given scope.

scoped tags are denoted by using a double colon

• "P1" is a regular tag (no double colon)
• "priority::1" is a scoped tag. The scope is "priority" and the variant is "1"
• "type::subtype::A" is a scoped tag, but only the last double colon is considered. So the scope is "type::subtype" and the variant is "A"

scoped labels have the following semantics

• it is an error to have two scoped labels on a vertex that have the same scope (ie "kind::usr" and "kind::sys" would be an error)
• if you add non-scoped labels using vertex configuration then you get a union of all tags which have been added using the configuration override mechanism
• if you add scoped labels, then the configuration override mechanism will replace existing labels with the same scope.

use cases:

• lightweight mechanism for enforcing mutually exclusive tags. For example, it never makes sense for a vertex to have multiple priorities.

this is fine:

.. vertex:: 01
   :tags: priority::1, component.x, milestone::a

   this is a tagged vertex directive.
   the 'priority' and 'milestone' are scoped labels.
   the component is not.

this is not fine:

.. vertex:: 01
   :tags: priority::1, priority::2

   this is a tagged vertex directive.
   it has two tags with the same scope ('priority') hence this would
   fail to build.

first noticed when creating vertices using myst parser.

Build errors are generated (and visible in the HTML output) when vertices contain headers.

#43 addressed the build errors, and the document is now generated correctly. However the layout isn't quite right. In my testing, a vertex with headers had the id and links information moved from the top of the vertex to the bottom in the rendered output.

Will need to investigate why that is happening...

see sphinx-doc/sphinx#11001