reST: Support explicit titles for cross-references
Open
Nobody has claimed this yet.
enhancement
- Dominant language
- Python
- Stars
- 2.5k
- Forks
- 228
- PR merge metrics
- No merged PRs in 30d
Description
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
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the rendering with the shown init.py docstring and README.rst, starting with the .. include:: directive and the :ref: links in README.rst. Compare the rendered output with the expected reStructuredText behavior and confirm that included content preserves explicit cross-reference titles.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100