reST: Support explicit titles for cross-references

[rhelmot]

Problem Description

I would like to .. include:: ../README.rst in my __init__.py module docstring. However, it appears to be parsed as markdown, despite the fact that it has the appropriate file extension and my docstring format is set to rst (i.e. left as default). Is this a missing feature, or am I doing something wrong?

__init__.py

"""
.. include:: ../README.rst
"""

README.rst

...
A :ref:`Task` is connected to repositories through **:ref:`links <Link>`**. A link is a repository plus a collection of properties describing the repository's relationship to the task - i.e. whether it is input or output, whether it should inhibit dependent tasks from starting, etc.
...

rendered

System Information

pdoc: 12.3.0
Python: 3.10.6
Platform: Linux-5.17.0-1021-oem-x86_64-with-glibc2.35

[mhils]

Are you running pdoc with --docformat restructuredtext?

[rhelmot]

Yes.

[mhils]

Ì think the problem here is unrelated to .. include::, it's much rather that we don't support :ref:.

:py:class:`Task`

works as expected for me. Is :ref: something that is properly documented somewhere?

[rhelmot]

Ah, hm. I've been using the sphinx documentation to see what my options were in terms of rst markup. I will switch to :py:class:. Is there a listing somewhere of which roles are supported by pdoc?

[rhelmot]

I am still struggling to get these links working.

README.rst

A :py:class:`Task <pydatatask.task.Task>` is connected to repositories through **:py:class:`links <pydatatask.task.Link>`**. A link is a repository plus a collection of properties describing the repository's relationship to the task - i.e. whether it is input or output, whether it should inhibit dependent tasks from starting, etc.

rendered

[mhils]

Yeah, I think that's extended rST syntax we don't support (yet).

:py:class:`Task`

works if Task is defined in the same file, otherwise

:py:class:`pydatatask.task.Task`

does the trick. I'm happy to accept contributions for this, but it's nothing I'll be actively pursuing.