2.6.2: sphinx warnings `reference target not found`

Open
  • Is something wrong?
#172 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@amritamishra01 is already working on this.

Since Nov 23, 2025.

  • #223 by @amritamishra01 — open

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
42/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
python
Domain
documentation

Research direction

Run the reported sphinx-build -n -T -b man doc build/sphinx/man command and inspect the warnings in doc/run_benchmark.rst, doc/system.rst, doc/api.rst, and doc/changelog.rst. Review the listed missing references and title warning, then rebuild the man pages to verify that the reported warnings are resolved.

Written by the indexing model from the issue text.

Description

On building my packages I'm using sphinx-build command with -n switch which shows warmings about missing references. These are not critical issues.
Here is the output with warnings:

+ /usr/bin/sphinx-build -n -T -b man doc build/sphinx/man
Running Sphinx v7.1.2
making output directory... done
WARNING: html_static_path entry 'static' does not exist
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 11 added, 0 changed, 0 removed
reading sources... [100%] user_guide
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/run_benchmark.rst:195: WARNING: Title underline too short.

Specializer statistics (``pystats``)
==================================
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/run_benchmark.rst:195: WARNING: Title underline too short.

Specializer statistics (``pystats``)
==================================
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... pyperf.1 { user_guide run_benchmark analyze cli runner system developer_guide examples api changelog } /home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/run_benchmark.rst:109: WARNING: py:attr reference target not found: Runner.inner_loops
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/system.rst:24: WARNING: py:func reference target not found: os.sched_setaffinity
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/api.rst:196: WARNING: py:class reference target not found: (datetime.datetime, datetime.datetime) or None
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/api.rst:225: WARNING: py:class reference target not found: int or float
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/api.rst:247: WARNING: py:class reference target not found: int or float
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/api.rst:256: WARNING: py:class reference target not found: int or float
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/api.rst:265: WARNING: py:class reference target not found: int or float
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/api.rst:284: WARNING: py:data reference target not found: sys.stdin
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/api.rst:377: WARNING: py:class reference target not found: Benchmark or BenchmarkSuite
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/api.rst:417: WARNING: py:class reference target not found: (datetime.datetime, datetime.datetime) or None
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/api.rst:456: WARNING: py:data reference target not found: sys.stdin
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/api.rst:599: WARNING: py:func reference target not found: time.perf_counter
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/api.rst:629: WARNING: py:func reference target not found: time.perf_counter
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/api.rst:658: WARNING: py:class reference target not found: argparse.ArgumentParser
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/changelog.rst:454: WARNING: py:func reference target not found: Benchmark.bench_func
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/changelog.rst:454: WARNING: py:func reference target not found: Benchmark.bench_sample_func
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/changelog.rst:560: WARNING: py:func reference target not found: perf.python_implementation
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/changelog.rst:560: WARNING: py:func reference target not found: perf.python_has_jit
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/changelog.rst:621: WARNING: py:class reference target not found: Metadata
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/changelog.rst:652: WARNING: py:class reference target not found: perf.BenchmarkSuite
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/changelog.rst:671: WARNING: py:meth reference target not found: perf.Benchmark.median
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/changelog.rst:672: WARNING: py:attr reference target not found: perf.Benchmark.metadata
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/changelog.rst:720: WARNING: py:meth reference target not found: TextRunner.bench_sample_func
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/changelog.rst:724: WARNING: py:func reference target not found: perf.is_significant
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/changelog.rst:725: WARNING: py:class reference target not found: perf.Benchmark
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/changelog.rst:726: WARNING: py:class reference target not found: perf.Benchmark
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/changelog.rst:727: WARNING: py:attr reference target not found: TextRunner.inner_loops
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/changelog.rst:727: WARNING: py:class reference target not found: TextRunner
/home/tkloczko/rpmbuild/BUILD/pyperf-2.6.2/doc/changelog.rst:736: WARNING: py:class reference target not found: TextRunner
done
build succeeded, 32 warnings.

You can peak on fixes that kind of issues in other projects
https://github.com/RDFLib/rdflib-sqlalchemy/issues/95
https://github.com/RDFLib/rdflib/pull/2036
https://github.com/click-contrib/sphinx-click/commit/abc31069
https://github.com/frostming/unearth/issues/14
https://github.com/jaraco/cssutils/issues/21
https://github.com/latchset/jwcrypto/pull/289
https://github.com/latchset/jwcrypto/pull/289
https://github.com/pypa/distlib/commit/98b9b89f
https://github.com/pywbem/pywbem/pull/2895
https://github.com/sissaschool/elementpath/commit/bf869d9e
https://github.com/sissaschool/xmlschema/commit/42ea98f2
https://github.com/sqlalchemy/sqlalchemy/commit/5e88e6e8

Dominant language
Python
Stars
967
Forks
112
Avg merge
5d 8h
Merged PRs (30d)
9

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

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.

More from psf/pyperf

All issues in psf/pyperf

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.