5.4.0: sphinx warnings `reference target not found`

Open

#285 opened on Jun 11, 2022 0 comments 0 reactions 0 assignees View on GitHub

Dominant language: Python
Stars: 313
Forks: 176
PR merge metrics: No merged PRs in 30d

Description

First of all currently it is not possible to use straight `sphinx-build` command to build documentation out of source tree

```console
+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v5.0.1
WARNING: Invalid configuration value found: 'language = None'. Update your configuration to a valid langauge code. Falling back to 'en' (English).
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://jupyter-client.readthedocs.io/en/stable/objects.inv...
loading intersphinx inventory from https://nbconvert.readthedocs.org/en/stable/objects.inv...
loading intersphinx inventory from https://jupyter-notebook.readthedocs.org/en/stable/objects.inv...
intersphinx inventory has moved: https://jupyter-notebook.readthedocs.org/en/stable/objects.inv -> https://jupyter-notebook.readthedocs.io/en/stable/objects.inv
intersphinx inventory has moved: https://nbconvert.readthedocs.org/en/stable/objects.inv -> https://nbconvert.readthedocs.io/en/stable/objects.inv
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 5 added, 0 changed, 0 removed
reading sources... [100%] markup
WARNING: autodoc: failed to import function 'read' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'reads' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'write' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'writes' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import class 'NotebookNode' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'from_dict' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'convert' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'validate' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import class 'ValidationError' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'v4.new_notebook' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'v4.new_code_cell' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'v4.new_markdown_cell' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'v4.new_raw_cell' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'v4.new_output' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import function 'v4.output_from_msg' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import class 'sign.NotebookNotary' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import class 'sign.SignatureStore' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import class 'sign.SQLiteSignatureStore' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
WARNING: autodoc: failed to import class 'sign.MemorySignatureStore' from module 'nbformat'; the following exception was raised:
No module named 'nbformat'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-nbformat.3 { format_description markup api changelog } /home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/docs/api.rst:40: WARNING: py:class reference target not found: NotebookNode
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/docs/api.rst:62: WARNING: py:class reference target not found: NotebookNode
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/docs/api.rst:103: WARNING: py:class reference target not found: SignatureStore
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/docs/api.rst:117: WARNING: py:class reference target not found: NotebookNotary
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/docs/changelog.rst:135: WARNING: py:func reference target not found: nbformat.validate
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/docs/changelog.rst:150: WARNING: py:func reference target not found: nbformat.read
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/docs/changelog.rst:150: WARNING: py:func reference target not found: nbformat.write
/home/tkloczko/rpmbuild/BUILD/nbformat-5.4.0/docs/changelog.rst:152: WARNING: py:func reference target not found: nbformat.validate
done
build succeeded, 28 warnings.
```

First part of those fixes can be fixed by patch like below:
```patch
--- a/docs/conf.py~ 2022-05-05 00:03:27.000000000 +0000
+++ b/docs/conf.py 2022-05-05 00:04:32.758233565 +0000
@@ -15,7 +15,9 @@
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))

# -- General configuration ------------------------------------------------
```

This patch fixes what is in the comment and that can of fix is suggested in sphinx example copy.py https://www.sphinx-doc.org/en/master/usage/configuration.html#example-of-configuration-file

Than .. on building my packages I'm using `sphinx-build` command with `-n` switch which shows warmings about missing references. These are not critical issues.

Summary warnings with that patch:

You can peak on fixes that kind of issues in other projects
https://github.com/latchset/jwcrypto/pull/289
https://github.com/click-contrib/sphinx-click/commit/abc31069
https://github.com/latchset/jwcrypto/pull/289
https://github.com/RDFLib/rdflib-sqlalchemy/issues/95
https://github.com/sissaschool/elementpath/commit/bf869d9e
https://github.com/jaraco/cssutils/issues/21

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

5.4.0: sphinx warnings `reference target not found`

Description

Contributor guide

Assessment

Get new issues in your inbox