diff --git a/docs/conf.py b/docs/conf.py index bb5d928a8d..d64c4ccb0c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -271,6 +271,9 @@ def __getattr__(cls, name): os.makedirs('spec', exist_ok=True) for area in areas: with open('{}.rst'.format(area.lstrip('/')), 'w') as doc: + # Anchor and title + doc.write(f'.. _{area}:\n\n') doc.write('{}\n{}\n'.format(areas[area], '=' * len(areas[area]))) + # Included stories for story in tree.stories(names=[area], whole=True): doc.write(story.export(title=story.name != area)) diff --git a/docs/spec.rst b/docs/spec.rst index 3125ca1b22..40236d9a92 100644 --- a/docs/spec.rst +++ b/docs/spec.rst @@ -18,24 +18,31 @@ data duplication and maintenance. The following metadata levels are defined: Level 0 - Core attributes such as ``summary`` for short overview, - ``description`` for detailed texts or the ``order`` which are - common and can be used across all metadata levels. + :ref:`/spec/core` attributes such as :ref:`/spec/core/summary` + for short overview, :ref:`/spec/core/description` for detailed + texts or the :ref:`/spec/core/order` which are common and can + be used across all metadata levels. Level 1 - Metadata closely related to individual test cases such as - the ``test`` script, directory ``path`` or maximum - ``duration`` which are stored directly with the test code. + Metadata closely related to individual :ref:`/spec/tests` such + as the :ref:`/spec/tests/test` script, directory + :ref:`/spec/tests/path` or maximum :ref:`/spec/tests/duration` + which are stored directly with the test code. Level 2 - Description of how to ``provision`` the environment for - testing and how to ``prepare`` it or which frameworks should - be used to ``execute`` tests relevant for given ``artifact``. + This level represents :ref:`/spec/plans` made up of individual + :ref:`/spec/steps` describing how to + :ref:`/spec/steps/provision` the environment for testing and + how to :ref:`/spec/steps/prepare` it or which frameworks + should be used to :ref:`/spec/steps/execute` tests relevant + for given :ref:`/spec/plans/artifact`. Level 3 - A user ``story`` can be used to define expected features of - the application and to easily track which functionality has - been already ``implemented``, ``tested`` and ``documented``. + User :ref:`/spec/stories` can be used to define expected + features of the application and to easily track which + functionality has been already + :ref:`/spec/stories/implemented`, :ref:`/spec/stories/tested` + and :ref:`/spec/stories/documented`. .. toctree:: :maxdepth: 2 diff --git a/tmt/base.py b/tmt/base.py index ed1a2fbf7c..aa5ec7de8c 100644 --- a/tmt/base.py +++ b/tmt/base.py @@ -542,10 +542,11 @@ def export(self, format_='rst', title=True): output = '' - # Title + # Title and its anchor if title: depth = len(re.findall('/', self.name)) - 1 title = re.sub('.*/', '', self.name) + output += f'\n.. _{self.name}:\n' output += '\n{}\n{}\n'.format(title, '=~^:-><'[depth] * len(title)) # Summary, story and description