search

falconry / falcon

The no-magic web data plane API and microservices framework for Python developers, with a focus on reliability, correctness, and performance at scale.
https://falcon.readthedocs.io/en/stable/
Apache License 2.0
9.51k stars 937 forks source link

3.0.1: sphinx warnings #2007

Closed kloczek closed 2 years ago

kloczek commented 2 years ago 
+ /usr/bin/python3 setup.py build_sphinx -b man --build-dir build/sphinx
running build_sphinx
Running Sphinx v4.3.2
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
Starting new HTTPS connection (1): docs.python.org:443
https://docs.python.org:443 "GET /3/objects.inv HTTP/1.1" 200 112797
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 52 added, 0 changed, 0 removed
reading sources... [100%] user/tutorial-asgi
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-falcon.3 { user/index user/intro user/install user/quickstart user/tutorial user/tutorial-asgi user/recipes/index user/recipes/header-name-case user/recipes/multipart-mixed user/recipes/output-csv user/recipes/pretty-json user/recipes/request-id user/faq deploy/index deploy/intro deploy/nginx-uwsgi community/index community/help community/contribute api/index api/app api/request_and_response api/request_and_response_wsgi api/request_and_response_asgi api/websocket api/cookies api/status api/errors api/media api/multipart api/redirects api/middleware api/cors api/hooks api/routing api/inspect api/util api/testing changes/index changes/3.0.1 changes/3.0.0 changes/2.0.0 changes/1.4.1 changes/1.4.0 changes/1.3.0 changes/1.2.0 changes/1.1.0 changes/1.0.0 changes/0.3.0 changes/0.2.0 } /home/tkloczko/rpmbuild/BUILD/falcon-3.0.1/docs/api/media.rst:166: WARNING: more than one target found for 'any' cross-reference 'Handlers': could be :py:class:`falcon.media.Handlers` or :py:class:`falcon.media.handlers.Handlers`
/home/tkloczko/rpmbuild/BUILD/falcon-3.0.1/docs/api/media.rst:193: WARNING: more than one target found for 'any' cross-reference 'Handlers': could be :py:class:`falcon.media.Handlers` or :py:class:`falcon.media.handlers.Handlers`
done
build succeeded, 2 warnings.
vytas7 commented 2 years ago

Hi @kloczek! Similar to #2006, we cannot really do much here.

Our tox environment for documentation (docs) is set to fail upon any warnings. This used to work when 3.0.1 was just released with the relevant Sphinx version at that time, however later Sphinx versions started picking on these multiple targets.

The docs have been cleaned up and upgraded to support the current Sphinx version in https://github.com/falconry/falcon/pull/1923, so the master branch should work fine, as evidenced by our recent CI runs. Otherwise, if you want to package 3.0.1 as-is, you need to maintain a patch pinning Sphinx < 3.5.0 as it was before merging the said PR.