ociu/sphinx-traceability-extension

Traceability extension for Sphinx documentation generator

sphinx-traceability-extension's Issues

Item matrix templates

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.

Warnings don't display line number information

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.

List/table titles not working

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.

Missing setup.py

Hi,
nice extension!

Would you consider adding a setup.py so it can be installed etc.?

Thanks

Newline not supported in :trace: relationships

Relationships indicated in :trace: option should be separated either by space or newline (the latter recommended for improving readability).

Spaces work, but newline not.

Item template: cannot display automatic reverse relationships

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')

Item templates

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 }}
"""

Make relationship options work

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.

How to add extension?

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

Requirement Traceability Matrix

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.

If no traceability directives are used, the sphinx build fails

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

Directives in docstrings possible?

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.

sphinx.util.compat.Directive is deprecated and will be removed in Sphinx 1.7

RemovedInSphinx17Warning: sphinx.util.compat.Directive is deprecated and will be removed in Sphinx 1.7, please use docutils' instead.

Consider adding the sphinx-extension GitHub topic

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.

Console traceability debug output

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.

Incompatibility with .. only (and .. ifconfig)

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

• the content of the item does not show up in the document : ok
• the item does still show up in the item-list, and item-matrix automatically generated lists/tables

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

Matrix sources on same line in PDF

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.