Anonymous link breaks plugin docs generation

[psss]

When an anonymous rst link is used in a plugin docstring, import of the plugin fails. Example link:

See the `Pylero Documentation`__ for more details on how
to configure the ``pylero`` module.

__ https://github.com/RedHatQE/pylero

Here's a make docs failure:

Extension error:
Handler <function generate_tmt_docs at 0x7fc1fc26ac00> for event 'config-inited' threw an exception (exception: Command '['make', 'generate']' returned non-zero exit status 2.)

And the full import traceback:

>>> import tmt.steps.report.polarion
Traceback (most recent call last):
  File "<python-input-1>", line 1, in <module>
    import tmt.steps.report.polarion
  File "/home/psss/git/tmt/tmt/steps/report/polarion.py", line 209, in <module>
    @tmt.steps.provides_method('polarion')
     ~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^
  File "/home/psss/git/tmt/tmt/steps/__init__.py", line 1360, in _method
    plugin_method = Method(
        name, cls, doc=doc, order=order, installation_hint=installation_hint
    )
  File "/home/psss/git/tmt/tmt/steps/__init__.py", line 1300, in __init__
    tmt.utils.rest.render_rst(doc, tmt.log.Logger.get_bootstrap_logger())
    ~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/psss/git/tmt/tmt/utils/rest.py", line 413, in render_rst
    document.walkabout(visitor)
    ~~~~~~~~~~~~~~~~~~^^^^^^^^^
  File "/home/psss/.local/share/hatch/env/virtual/tmt/v_yBwOy-/dev/lib/python3.13/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
       ~~~~~~~~~~~~~~~^^^^^^^^^
  File "/home/psss/.local/share/hatch/env/virtual/tmt/v_yBwOy-/dev/lib/python3.13/site-packages/docutils/nodes.py", line 178, in walkabout
    visitor.dispatch_visit(self)
    ~~~~~~~~~~~~~~~~~~~~~~^^^^^^
  File "/home/psss/.local/share/hatch/env/virtual/tmt/v_yBwOy-/dev/lib/python3.13/site-packages/docutils/nodes.py", line 1992, in dispatch_visit
    return method(node)
  File "/home/psss/git/tmt/tmt/utils/rest.py", line 354, in unknown_visit
    raise GeneralError(f"Unhandled ReST node '{node}'.")
tmt.utils.GeneralError: Unhandled ReST node '<target anonymous="1" ids="['target-1']" refuri="https://github.com/RedHatQE/pylero"/>'.

[psss]

Seems that directly defined links cause the same problem:

Custom name like `Python <http://www.python.org/>`_.

[happz]

Makes sense, ReST CLI rendering is by no means complete. Support for :ref: was added recently, this will be similar issue.

[psss]

This is blocking documentation improvements, raising priority.

[LecrisUT]

I wonder if this could be refactored to use sphinx primitives instead. That should help support sphinx roles better, but it would change the dependency though.

I looked into the autodoc at some point and it should work for RST documents (not out-of-the-box for markdown though). We could create a dummy sphinx project for the rendering, but I think there are some api to build individual pages.

[happz]

I wonder if this could be refactored to use sphinx primitives instead. That should help support sphinx roles better, but it would change the dependency though.

Which may not be the worst thing under the Sun, but it's also not the best one ever. I'm not sure how to connect the dots, but the feature here is a simple, native ReST construct, nothing remotely close to Sphinx, so I would be worried adding Sphinx to the mix would make things more complicated.

I looked into the autodoc at some point and it should work for RST documents (not out-of-the-box for markdown though). We could create a dummy sphinx project for the rendering, but I think there are some api to build individual pages.

A bit of a context here: the issue discussed above is in ReST rendering for CLI, e.g. tmt run report -h polarion --help - options, plugin doc(string), printed to a console, i.e. ReST -> text, colors (aka ANSI control characters) and a bit of indentation and fancy formatting.

In other words, no plugin API, Sphinx is not involved, and it's implemented with a call to docutils and a very simple tree walking, to produce some styled lines of text. Look at tmt.utils.rest, it's really trivial. Wouldn't adding Sphinx into the mix make the task of "show nicely formatted docstring of a plugin when its --help is invoked" more entangled?

If you have ideas how to make it simpler, I'm all ears, but there are some must haves: render an arbitrary ReST content as a blob of text suitable for printing to console, follow color theme picked by tmt user, fewer dependencies. It's not just plugin docstrings, but CLI options (we are hooked into help rendering in Click) and random templates too, like a list of discovered plugins, so we are more after a "generic ReST rendering engine" rather than more specialized "turning Python code into HTML/man/console/..." tool :/

[LecrisUT]

Ah, so that's why the solution for these is to make the links no-ops. So the parser that renders the rst to terminal output (this one using the rst renderer) is different than the one that makes the html pages (those are just parsed directly by sphinx?).

[happz]

Ah, so that's why the solution for these is to make the links no-ops. So the parser that renders the rst to terminal output (this one using the rst renderer) is different than the one that makes the html pages (those are just parsed directly by sphinx?).

Absolutely, we are not extending Sphinx, just a very basic docstring-to-console-but-nicely-if-possible rendering engine. The primary consumer of these docstrings remains Sphinx, autodocs, HTML builder (and humans, of course) so we use all the fancy stuff there, and the issue here is that our simple CLI-focused rendering engine lacked support for something Sphinx can already translate to HTML.

No-ops are not necessarily the best possible solution, but it's probably good enough for the target environment. Terminals often support opening links that were printed out, so there might be an improvement possible.