Add a trivial handler for :ref: role when rendering CLI help

[happz]

Sphinx takes care of it when building (HTML) docs, but for CLI help, we need to provide a handler of our own. But even a simple one is enough.

Pull Request Checklist

• implement the feature
• extend the test coverage

[psss]

Tried to render something for the discover --how fmf plugin, but ended with this error:

TypeError: role_ref() missing 2 required positional arguments: 'options' and 'content'

[happz]

Tried to render something for the discover --how fmf plugin, but ended with this error:

TypeError: role_ref() missing 2 required positional arguments: 'options' and 'content'

Should be addressed in 79afa3e

[thrix]

Tried to render something for the discover --how fmf plugin, but ended with this error:

TypeError: role_ref() missing 2 required positional arguments: 'options' and 'content'

@psss nice catch! pls re-review

[thrix]

The Rawhide image was updated, restart the failing test

/packit retest-failed

[thrix]

@happz can you share which help should be improved? I am failing to find some example to verify how it looks

[happz]

@happz can you share which help should be improved? I am failing to find some example to verify how it looks

It's used in prepare/feature plugins documentation. And it does nothing fancy, just emits the path :ref: points to.

[psss]

Tried with a simple ref in the fmf plugin:

diff --git a/tmt/steps/discover/fmf.py b/tmt/steps/discover/fmf.py
index 2c4f5d6e..592af006 100644
--- a/tmt/steps/discover/fmf.py
+++ b/tmt/steps/discover/fmf.py
@@ -277,6 +277,8 @@ class DiscoverFmf(tmt.steps.discover.DiscoverPlugin[DiscoverFmfStepData]):
     when you do not have write access to the remote test repository.
     The value should follow the ``adjust`` rules syntax.
 
+    Hmmm :ref:`/spec/plans/prepare/feature`...
+
     The following example adds an ``avc`` check for each discovered
     test, doubles its duration and replaces each occurrence of the word
     ``python3.11`` in the list of required packages.

Docs are successfully built and I can see the link in the tmt run discover -h fmf --help:

  The value should follow the adjust rules syntax.

  Hmmm /spec/plans/prepare/feature...

  The following example adds an avc check for each discovered

But there are also weird warnings when building the docs:

WARNING: autodoc: failed to import module 'cli.init' from module 'tmt'; the following exception was raised:
Traceback (most recent call last):
  File "/home/psss/.local/share/hatch/env/virtual/tmt/v_yBwOy-/docs/lib/python3.13/site-packages/sphinx/ext/autodoc/importer.py", line 143, in import_module
    return importlib.import_module(modname)
           ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^
  File "/usr/lib64/python3.13/importlib/__init__.py", line 88, in import_module
  ...
  File "/home/psss/.local/share/hatch/env/virtual/tmt/v_yBwOy-/docs/lib/python3.13/site-packages/sphinx/roles.py", line 134, in create_xref_node
    'refdoc': self.env.docname,
              ^^^^^^^^
  File "/home/psss/.local/share/hatch/env/virtual/tmt/v_yBwOy-/docs/lib/python3.13/site-packages/sphinx/util/docutils.py", line 480, in env
    return self.inliner.document.settings.env
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: 'Values' object has no attribute 'env'

@happz, are you able to reproduce the problem?

[happz]

Tried with a simple ref in the fmf plugin:

diff --git a/tmt/steps/discover/fmf.py b/tmt/steps/discover/fmf.py
index 2c4f5d6e..592af006 100644
--- a/tmt/steps/discover/fmf.py
+++ b/tmt/steps/discover/fmf.py
@@ -277,6 +277,8 @@ class DiscoverFmf(tmt.steps.discover.DiscoverPlugin[DiscoverFmfStepData]):
     when you do not have write access to the remote test repository.
     The value should follow the ``adjust`` rules syntax.
 
+    Hmmm :ref:`/spec/plans/prepare/feature`...
+
     The following example adds an ``avc`` check for each discovered
     test, doubles its duration and replaces each occurrence of the word
     ``python3.11`` in the list of required packages.

Docs are successfully built and I can see the link in the tmt run discover -h fmf --help:

  The value should follow the adjust rules syntax.

  Hmmm /spec/plans/prepare/feature...

  The following example adds an avc check for each discovered

But there are also weird warnings when building the docs:

WARNING: autodoc: failed to import module 'cli.init' from module 'tmt'; the following exception was raised:
Traceback (most recent call last):
  File "/home/psss/.local/share/hatch/env/virtual/tmt/v_yBwOy-/docs/lib/python3.13/site-packages/sphinx/ext/autodoc/importer.py", line 143, in import_module
    return importlib.import_module(modname)
           ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^
  File "/usr/lib64/python3.13/importlib/__init__.py", line 88, in import_module
  ...
  File "/home/psss/.local/share/hatch/env/virtual/tmt/v_yBwOy-/docs/lib/python3.13/site-packages/sphinx/roles.py", line 134, in create_xref_node
    'refdoc': self.env.docname,
              ^^^^^^^^
  File "/home/psss/.local/share/hatch/env/virtual/tmt/v_yBwOy-/docs/lib/python3.13/site-packages/sphinx/util/docutils.py", line 480, in env
    return self.inliner.document.settings.env
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: 'Values' object has no attribute 'env'

@happz, are you able to reproduce the problem?

Hmmm, unfortunately, I am able to reproduce. It looks like some conflicts between how Sphinx sets up the ReST parser, and how we do it. Seems to me Sphinx's role handler is called instead of ours.

[happz]

Tried with a simple ref in the fmf plugin:

diff --git a/tmt/steps/discover/fmf.py b/tmt/steps/discover/fmf.py
index 2c4f5d6e..592af006 100644
--- a/tmt/steps/discover/fmf.py
+++ b/tmt/steps/discover/fmf.py
@@ -277,6 +277,8 @@ class DiscoverFmf(tmt.steps.discover.DiscoverPlugin[DiscoverFmfStepData]):
     when you do not have write access to the remote test repository.
     The value should follow the ``adjust`` rules syntax.
 
+    Hmmm :ref:`/spec/plans/prepare/feature`...
+
     The following example adds an ``avc`` check for each discovered
     test, doubles its duration and replaces each occurrence of the word
     ``python3.11`` in the list of required packages.

Docs are successfully built and I can see the link in the tmt run discover -h fmf --help:

  The value should follow the adjust rules syntax.

  Hmmm /spec/plans/prepare/feature...

  The following example adds an avc check for each discovered

But there are also weird warnings when building the docs:

WARNING: autodoc: failed to import module 'cli.init' from module 'tmt'; the following exception was raised:
Traceback (most recent call last):
  File "/home/psss/.local/share/hatch/env/virtual/tmt/v_yBwOy-/docs/lib/python3.13/site-packages/sphinx/ext/autodoc/importer.py", line 143, in import_module
    return importlib.import_module(modname)
           ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^
  File "/usr/lib64/python3.13/importlib/__init__.py", line 88, in import_module
  ...
  File "/home/psss/.local/share/hatch/env/virtual/tmt/v_yBwOy-/docs/lib/python3.13/site-packages/sphinx/roles.py", line 134, in create_xref_node
    'refdoc': self.env.docname,
              ^^^^^^^^
  File "/home/psss/.local/share/hatch/env/virtual/tmt/v_yBwOy-/docs/lib/python3.13/site-packages/sphinx/util/docutils.py", line 480, in env
    return self.inliner.document.settings.env
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: 'Values' object has no attribute 'env'

@happz, are you able to reproduce the problem?

Hmmm, unfortunately, I am able to reproduce. It looks like some conflicts between how Sphinx sets up the ReST parser, and how we do it. Seems to me Sphinx's role handler is called instead of ours.

Hopefully addressed in 478fcb4. I was unable to teach Sphinx some reason, both Sphinx and docutils rely on global, module-level variables I was unable to reasonably modify just for our code. So, skipping ReST rendering of docstrings CLI would emit while running under the control of Sphinx.

[thrix]

All test failures are expected, see #3487 and rawhide is a known thing 1.41.1 in TF will fix