ociu / sphinx-traceability-extension Goto Github PK
View Code? Open in Web Editor NEWTraceability extension for Sphinx documentation generator
License: GNU General Public License v3.0
Traceability extension for Sphinx documentation generator
License: GNU General Public License v3.0
Have you thought about to add the generation of a requirement traceability matrix (like done here) or to provide a data interface that one may generate one externally? Or both... I would be interested in contribution.
As in #9, apply templates also to the item-matrix
nodes, so that the whole table format can be customized, even not being presented as a table.
One of the consequences of using templates for item-matrix
is that the item-list
directive would be no longer necessary, as a particular template could be defined to show only one part of a traceability matrix as a list. This would also allow more complex lists, such as lists with sublists.
Template would not only have as input the related items, but also the implied relationships, so that relationships could be also shown in the output.
Example template: item matrix as is generated now:
.. list-table:: {{ title }}
:header-rows: 1
* - Source
- Target
{% for line in table %}
* - {{ line.source }}
- {{ line.target }}
{% endfor %}
Another benefit is that this way, table generation code would be much, much simpler.
Instead of the annoying admonition
node formatting, provide a template mechanism so user can decide how to format items, in a similar way to how matplotlib plot directive does.
In order to allow different templates in the same project, regexps and/or class options could be used to decide which items a template should be applied to.
Example template: defining items as term-definition pairs, with highlighted caption as first definition line:
"""
{{ item_id }}
**{{ item_caption }}**
{{ item_body }}
"""
If you add the traceability
module to the list of sphinx extensions, but you don't actually use any of the new directives, the sphinx build fails.
Exception occurred:
File "/home/UNIXHOME/mlakata/p4/acq/Sequel/top/doc/sphinxcontrib/traceability.py", line 237, in process_item_nodes
all_items = sorted(env.traceability_all_items, key=naturalsortkey)
AttributeError: BuildEnvironment instance has no attribute 'traceability_all_items'
A simple fix is
def process_item_nodes(app, doctree, fromdocname):
...
env = app.builder.env
if not hasattr(env, 'traceability_all_items'):
return
Though specified for v0.1.0, the title argument passed to directives item-list
and item-matrix
has no effect in the output. To correct:
item-list
: remove argument. Title has no sense, as a title can be put before and there is no need to reference the list.item-matrix
: title should be inserted as in a table
directive, also as a reference.Just wanted to say you should consider adding the sphinx-extension topic, https://github.com/topics/sphinx-extension, to the repo so it is easier for others to find on the GitHub ecosystem. There are currently 96 other sphinx extensions that use that topic.
Is it possible to place the directives of the extension into docstrings? This would allow to use sphinx.ext.autodoc and other extensions which include docstrings into the documentation automatically.
Stereotypes are supported in syntax and stored, but not used for the moment. They should be used as the README states, to classify relationships and allow filtering.
RemovedInSphinx17Warning: sphinx.util.compat.Directive is deprecated and will be removed in Sphinx 1.7, please use docutils' instead.
It seems like when item directives (here: SW_REQ_001) reference other item directives (here: SW_TEST_001) which do not exist the user is just able to get informed about this by observing the document output (html, pdf, ...) of the .. item-matrix::
directive. Some debug or warning console output during the build process would be helpful to get around this manual traceability checking.
.. item:: SW_REQ_001 Some requirement.
:validated_by: SW_TEST_001
... like in /sphinx-traceability-extension/tests/docs/autodoc/docs/_build/index.html what you can build with #17
This issue will be addressed by #18.
An example warning is as follows:
sample_file.rst:None: WARNING: Traceability: cannot link to RQT-TEST-1234, item is not defined
It would be useful to have the line number included in the warning.
Relationships indicated in :trace: option should be separated either by space or newline (the latter recommended for improving readability).
Spaces work, but newline not.
When using the item-matrix
to produce HTML, and one target item has multiple source items, each source is on its own line.
But when generating latex / a PDF, these source items are all one the same line, and can create ugly wide tables that overflow the page borders.
Hello,
I was using the initial template implementation for items from a31affa. Very nice to be able to control how the information looks after rendering.
I discovered a shortcoming however. The plugin automatically generates a reverse relationship for every defined relationship. These reverse relationships are not available when the item-template is hit. So when you include these relationships in the template, they are not rendered in the html output.
This is the template I am using:
app.add_config_value('traceability_item_template',
"""
.. _item_{{ id }}:
.. admonition::
{{ id }}
{% if caption %}
**{{ caption }}**
{% endif %}
{% if depends_on %}
Depends on:
{%- for item in depends_on %}
:ref:`{{ item }}<item_{{ item }}>`
{% endfor %}
{% endif %}
{% if impacts_on %}
Impacts on:
{%- for item in impacts_on %}
:ref:`{{ item }}<item_{{ item }}>`
{% endfor %}
{% endif %}
{% if fulfills %}
Fulfills:
{%- for item in fulfills %}
:ref:`{{ item }}<item_{{ item }}>`
{% endfor %}
{% endif %}
{% if fulfilled_by %}
Fulfilled by:
{%- for item in fulfilled_by %}
:ref:`{{ item }}<item_{{ item }}>`
{% endfor %}
{% endif %}
{% if validates %}
Validates:
{%- for item in validates %}
:ref:`{{ item }}<item_{{ item }}>`
{% endfor %}
{% endif %}
{% if validated_by %}
Validated by:
{%- for item in validated_by %}
:ref:`{{ item }}<item_{{ item }}>`
{% endfor %}
{% endif %}
{{ content }}
""",
'env')
Hi,
nice extension!
Would you consider adding a setup.py so it can be installed etc.?
Thanks
Basic question.
I've done the pip install. Now how do import the extension? I tried adding to extensions
in conf.py
, but when I run make html
I get:
Extension error:
Could not import extension traceability (exception: No module named 'traceability')
make: *** [Makefile:20: html] Error 2
and
Extension error:
Could not import extension sphinxcontrib-traceability (exception: No module named 'sphinxcontrib-traceability')
make: *** [Makefile:20: html] Error 2
When an item is conditionally included in the document using the ..only directive (or the ..ifconfig) directive, and the condition on the tags is not met
syntax used:
.. only :: RANDOM_TAG_WHICH_IS_NOT_DEFINED_IN_CONF_DOT_PY
.. item:: my_item It is an item with a caption
:depends_on: another_item
This item does not show up in the document, but does show up in the generated lists and tables
Doc for ..only and how to specify tags on command line or conf.py, can be found here http://www.sphinx-doc.org/en/stable/markup/misc.html
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.