sphinx-doc / sphinx-doc/sphinx

[C++] Warning about reference target not being found for templated types

Open
#8,784 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

domains:cpp
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.