search

tantale / deprecated

Python @deprecated decorator to deprecate old python classes, functions or methods.
MIT License
298 stars 32 forks source link

1.2.13: sphinx warnings `reference target not found` #55

Closed kloczek closed 1 year ago

kloczek commented 2 years ago

First of all looks like it is not possible cleanly build documentation usinf raw sphinx-build command.

+ /usr/bin/sphinx-build -n -T -b man docs/source build/sphinx/man
Running Sphinx v4.5.0
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://wrapt.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from http://flask.pocoo.org/docs/1.0/objects.inv...
loading intersphinx inventory from https://docs.djangoproject.com/en/2.1/_objects/...
intersphinx inventory has moved: http://flask.pocoo.org/docs/1.0/objects.inv -> https://flask.palletsprojects.com/en/1.0.x/objects.inv
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 10 added, 0 changed, 0 removed
reading sources... [100%] white_paper
WARNING: autodoc: failed to import module 'deprecated'; the following exception was raised:
No module named 'deprecated'
WARNING: autodoc: failed to import module 'classic' from module 'deprecated'; the following exception was raised:
No module named 'deprecated'
WARNING: autodoc: failed to import module 'sphinx' from module 'deprecated'; the following exception was raised:
No module named 'deprecated'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-deprecated.3 { installation introduction tutorial sphinx_deco white_paper api changelog license contributing } /home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/tutorial.rst:20: WARNING: py:meth reference target not found: deprecated
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/tutorial.rst:120: WARNING: py:func reference target not found: deprecated.deprecated
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/tutorial.rst:155: WARNING: py:func reference target not found: deprecated.classic.deprecated
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/tutorial.rst:155: WARNING: py:func reference target not found: deprecated.sphinx.deprecated
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/tutorial.rst:200: WARNING: py:func reference target not found: deprecated.classic.deprecated
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/tutorial.rst:200: WARNING: py:func reference target not found: deprecated.sphinx.deprecated
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/sphinx_deco.rst:77: WARNING: py:func reference target not found: deprecated.sphinx.deprecated
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/sphinx_deco.rst:78: WARNING: py:func reference target not found: deprecated.sphinx.versionadded
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/sphinx_deco.rst:79: WARNING: py:func reference target not found: deprecated.sphinx.versionchanged
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:78: WARNING: py:mod reference target not found: asyncio.tasks
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:128: WARNING: py:mod reference target not found: flask.app
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:128: WARNING: py:mod reference target not found: flask.helpers
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:168: WARNING: py:exc reference target not found: flask.exthook.ExtDeprecationWarning
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:202: WARNING: py:mod reference target not found: django.utils.deprecation
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:204: WARNING: py:exc reference target not found: django.utils.deprecation.RemovedInDjango31Warning
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:206: WARNING: py:exc reference target not found: django.utils.deprecation.RemovedInDjango40Warning
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:208: WARNING: py:exc reference target not found: django.utils.deprecation.RemovedInNextVersionWarning
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:208: WARNING: py:exc reference target not found: django.utils.deprecation.RemovedInDjango40Warning
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:211: WARNING: py:exc reference target not found: django.utils.deprecation.RemovedInNextVersionWarning
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:215: WARNING: py:class reference target not found: django.contrib.postgres.forms.ranges.FloatRangeField
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:231: WARNING: py:exc reference target not found: django.utils.deprecation.RemovedInDjango31Warning
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:235: WARNING: py:meth reference target not found: django.conf.LazySettings.FILE_CHARSET
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:235: WARNING: py:class reference target not found: django.conf.LazySettings
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:255: WARNING: py:exc reference target not found: django.utils.deprecation.RemovedInDjango40Warning
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:267: WARNING: py:class reference target not found: django.utils.deprecation.warn_about_renamed_method
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:267: WARNING: py:class reference target not found: django.utils.deprecation.RenameMethodsBase
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:292: WARNING: py:class reference target not found: lxml.xpath._XPathEvaluatorBase`(:file:`src/lxml/xpath.pxi
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:312: WARNING: py:class reference target not found: lxml.etree._ElementTree
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:343: WARNING: py:func reference target not found: deprecated.sphinx.deprecated
CHANGELOG.rst:29: WARNING: py:func reference target not found: deprecated.sphinx.deprecated
CHANGELOG.rst:61: WARNING: py:mod reference target not found: deprecated.sphinx
CHANGELOG.rst:80: WARNING: py:class reference target not found: deprecated.sphinx.SphinxAdapter
CHANGELOG.rst:242: WARNING: py:class reference target not found: deprecated.classic.ClassicAdapter
CHANGELOG.rst:248: WARNING: py:class reference target not found: deprecated.classic.ClassicAdapter
CHANGELOG.rst:248: WARNING: py:class reference target not found: deprecated.sphinx.SphinxAdapter
CHANGELOG.rst:284: WARNING: py:mod reference target not found: deprecated.sphinx
CHANGELOG.rst:354: WARNING: py:func reference target not found: deprecated.deprecated
CHANGELOG.rst:422: WARNING: py:func reference target not found: deprecated.deprecated
CHANGELOG.rst:425: WARNING: py:mod reference target not found: deprecated
done
build succeeded, 42 warnings.

Fiirst part of warnings can be fixed by patch like below

--- a/docs/source/conf.py~      2022-05-13 08:06:41.000000000 +0000
+++ b/docs/source/conf.py       2022-05-13 08:10:22.286693027 +0000
@@ -17,9 +17,9 @@
 # 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.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../..'))

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

That patch is doing exacly what is mentioned in comment above modified lines. 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. Here is the output with warnings:

+ /usr/bin/sphinx-build -n -T -b man docs/source build/sphinx/man
Running Sphinx v4.5.0
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://wrapt.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from http://flask.pocoo.org/docs/1.0/objects.inv...
loading intersphinx inventory from https://docs.djangoproject.com/en/2.1/_objects/...
intersphinx inventory has moved: http://flask.pocoo.org/docs/1.0/objects.inv -> https://flask.palletsprojects.com/en/1.0.x/objects.inv
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 10 added, 0 changed, 0 removed
reading sources... [100%] white_paper
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-deprecated.3 { installation introduction tutorial sphinx_deco white_paper api changelog license contributing } /home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/tutorial.rst:120: WARNING: py:func reference target not found: deprecated.deprecated
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:78: WARNING: py:mod reference target not found: asyncio.tasks
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:128: WARNING: py:mod reference target not found: flask.app
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:128: WARNING: py:mod reference target not found: flask.helpers
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:168: WARNING: py:exc reference target not found: flask.exthook.ExtDeprecationWarning
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:202: WARNING: py:mod reference target not found: django.utils.deprecation
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:204: WARNING: py:exc reference target not found: django.utils.deprecation.RemovedInDjango31Warning
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:206: WARNING: py:exc reference target not found: django.utils.deprecation.RemovedInDjango40Warning
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:208: WARNING: py:exc reference target not found: django.utils.deprecation.RemovedInNextVersionWarning
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:208: WARNING: py:exc reference target not found: django.utils.deprecation.RemovedInDjango40Warning
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:211: WARNING: py:exc reference target not found: django.utils.deprecation.RemovedInNextVersionWarning
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:215: WARNING: py:class reference target not found: django.contrib.postgres.forms.ranges.FloatRangeField
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:231: WARNING: py:exc reference target not found: django.utils.deprecation.RemovedInDjango31Warning
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:235: WARNING: py:meth reference target not found: django.conf.LazySettings.FILE_CHARSET
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:235: WARNING: py:class reference target not found: django.conf.LazySettings
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:255: WARNING: py:exc reference target not found: django.utils.deprecation.RemovedInDjango40Warning
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:267: WARNING: py:class reference target not found: django.utils.deprecation.warn_about_renamed_method
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:267: WARNING: py:class reference target not found: django.utils.deprecation.RenameMethodsBase
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:292: WARNING: py:class reference target not found: lxml.xpath._XPathEvaluatorBase`(:file:`src/lxml/xpath.pxi
/home/tkloczko/rpmbuild/BUILD/deprecated-1.2.13/docs/source/white_paper.rst:312: WARNING: py:class reference target not found: lxml.etree._ElementTree
CHANGELOG.rst:354: WARNING: py:func reference target not found: deprecated.deprecated
CHANGELOG.rst:422: WARNING: py:func reference target not found: deprecated.deprecated
done
build succeeded, 22 warnings.
tantale commented 1 year ago

Well, I can't reproduce your issue.

Using a Python 3.8 virtualenv with the following versions:

> pip list
Package    Version
---------- -------
pip        23.1.2
setuptools 67.8.0
wheel      0.40.0

You can execute:

pip install -e .

Then, if you only want to install the requirements for Sphinx, to can try:

pip install 'sphinx < 2' 'jinja2~=3.0.3'

Then, to build the documentation, have to execute:

sphinx-build -b html -d dist/docs/doctrees docs/source/ dist/docs/html/

Everything run perfectly…

kloczek commented 1 year ago

You forgot about -n param.

kloczek commented 1 year ago

Running Sphinx v4.5.0

Why you are using so ols sphinx version? 🤔