Support fmf name references in docs, update spec

Every title now has a corresponding fmf name anchor so that it can
be linked from any page across the whole documentation. The main
specification page has been updated with links to individual
levels.

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

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

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