Improve the plugin docs generation

[psss]

I just tried to add a subsection in the discover.fmf plugin but the generate-plugins.py script fails with:

Failed to import the 'tmt.steps.discover.fmf' module from '/home/psss/git/tmt/docs'.

The same happend when I tried to reference a specification using:

:ref:`/spec/core/adjust`

It would be also nice to keep the paragraph separation in the --help generated messages. Currently the two adjacent paragraphs (with no example or items between them) are joined together.

[happz]

Can you share the change that led to failed import? A change in a docstring shouldn’t have such an effect :/

[happz]

^^ this is for paragraphs glued together.

[psss]

^^ this is for paragraphs glued together.

Excellent! Merged.

Can you share the change that led to failed import? A change in a docstring shouldn’t have such an effect :/

Yes, it's just adding :ref: to the docstring. The error looks like this:

scripts/generate-plugins.py discover templates/plugins.rst.j2 plugins/discover.rst
<rst-doc>:82: (ERROR/3) Unknown interpreted text role "ref".
Failed to import the 'tmt.steps.discover.fmf' module from '/home/psss/git/tmt/docs'.