6.0.0: sphinx warnings `reference target not found`

[kloczek]

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:

```console + /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man Running Sphinx v7.0.1 making output directory... done loading intersphinx inventory from https://docs.python.org/3/objects.inv... building [mo]: targets for 0 po files that are out of date writing output... building [man]: all manpages updating environment: [new config] 4 added, 0 changed, 0 removed reading sources... [100%] troubleshooting looking for now-outdated files... none found pickling environment... done checking consistency... done writing... python-pyngrok.3 { api integrations troubleshooting } /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/ngrok.py:docstring of pyngrok.ngrok.api_request:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/ngrok.py:docstring of pyngrok.ngrok.api_request:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/ngrok.py:docstring of pyngrok.ngrok.api_request:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/ngrok.py:docstring of pyngrok.ngrok.api_request:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/ngrok.py:docstring of pyngrok.ngrok.connect:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/ngrok.py:docstring of pyngrok.ngrok.connect:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/ngrok.py:docstring of pyngrok.ngrok.connect:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/ngrok.py:docstring of pyngrok.ngrok.connect:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/ngrok.py:docstring of pyngrok.ngrok.connect:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/ngrok.py:docstring of pyngrok.ngrok.disconnect:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/ngrok.py:docstring of pyngrok.ngrok.get_ngrok_process:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/ngrok.py:docstring of pyngrok.ngrok.get_tunnels:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/ngrok.py:docstring of pyngrok.ngrok.get_version:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/ngrok.py:docstring of pyngrok.ngrok.install_ngrok:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/ngrok.py:docstring of pyngrok.ngrok.kill:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/ngrok.py:docstring of pyngrok.ngrok.run:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/ngrok.py:docstring of pyngrok.ngrok.run:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/ngrok.py:docstring of pyngrok.ngrok.set_auth_token:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/ngrok.py:docstring of pyngrok.ngrok.update:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/conf.py:docstring of pyngrok.conf.PyngrokConfig:1: WARNING: py:class reference target not found: types.FunctionType /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/installer.py:docstring of pyngrok.installer._download_file:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/installer.py:docstring of pyngrok.installer._download_file:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/installer.py:docstring of pyngrok.installer.get_default_config:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/installer.py:docstring of pyngrok.installer.get_ngrok_config:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/installer.py:docstring of pyngrok.installer.install_default_config:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/installer.py:docstring of pyngrok.installer.install_default_config:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/installer.py:docstring of pyngrok.installer.install_ngrok:1: WARNING: py:class reference target not found: optional /home/tkloczko/rpmbuild/BUILD/pyngrok-6.0.0/pyngrok/installer.py:docstring of pyngrok.installer.install_ngrok:1: WARNING: py:class reference target not found: optional done build succeeded, 28 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

[alexdlaird]

I don't have plans to fix this, as the docs build fine with a proper distinction between the parameter type (for instance, int), and the string "optional" next to it. The link builds properly so you can click int and be taken to its docs, and the reader still sees that the parameter is optional. If Sphinx gives a proper way to document when a parameter is optional, I'll modify the code then, but until then, the context it gives readers in the docs outweighs the nit here, in my view.

[kloczek]

Please look one more time. This issue affects formats like html, pdf and qch. In rendered document there are only highlighted keywords instead links.

[alexdlaird]

Please provide an example of where you're seeing this. Here are examples of the links properly rendering (and clickable) on ReadTheDocs: https://pyngrok.readthedocs.io/en/latest/api.html#module-pyngrok.installer

Looks identical in html generated locally as well.

If they are not showing in another HTML context, that is likely due to a templating issue (that's my guess), but happy to look with more context provided. If they aren't showing in other file formats like PDF, etc., the project has never supported those, so likely a lot else isn't working there as well. Neither of these should have any effect on packages depending on pyngrok though (save for a warning), but correct me if I'm wrong.

[alexdlaird]

A nice side effect of adding Python type hinting to pyngrok is that these warnings have now been resolved, since Optional is a type hint rather than a part of the doc string. So bumping to the pyngrok 7 should get rid of these warnings for you.