sphinx-doc / sphinx-doc/sphinx
[C++] Warning about reference target not being found for templated types
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Describe the bug
My documentation contains the following line (*):
.. cpp:var:: xbt::signal< void(const Actor &, const Host &previous_location)> Actor::on_host_change
This produces the following warning:
docstring of Actor::on_host_change:3: WARNING: cpp:identifier reference target not found: xbt::signal<void(const Actor&, const Host &previous_location)>
(*) note that this line does not actually appear in my source, but it's generated by an extension of mine, see below
To Reproduce
Steps to reproduce the behavior:
$ git clone https://framagit.org/simgrid/simgrid.git
$ cd simgrid
$ pip install -r docs/requirements.txt
$ cd docs
$ ./Build.sh
Expected behavior
I think that this warning should not be produced, as we don't want to document every variation of a given template. To me, this is very similar to #3320, but this time for the cpp domain.
Environment info
- OS: Linux
- Python version: 3.9.1+
- Sphinx version: 3.4.3-1 (from Debian)
- Sphinx extensions: docs/sources/_ext/autodoxy.py in the simgrid project is generating the cpp:var line from doxygen XML files
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
Run the reproduction from docs/requirements.txt and docs/Build.sh, using docs/sources/_ext/autodoxy.py as the source of the generated cpp:var directive. Trace how the C++ domain resolves the templated reference and determine how to avoid the warning for this case. Done means the documented build no longer emits the missing-reference warning.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp, python
- Domain
- documentation, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100