Sphinx 3+ support

[slav0nic]

Sphinx 3 was released with some changes

Current build (https://travis-ci.org/github/Pylons/pyramid/jobs/676530356#L248) can be fixed with

diff --git a/docs/conf.py b/docs/conf.py
index 472485380..613f38dca 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -379,9 +379,9 @@ def app_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
 
 def setup(app):
     app.add_role('app', app_role)
-    app.add_directive('frontmatter', FrontMatter, 1, (0, 0, 0))
-    app.add_directive('mainmatter', MainMatter, 1, (0, 0, 0))
-    app.add_directive('backmatter', BackMatter, 1, (0, 0, 0))
+    app.add_directive('frontmatter', FrontMatter)
+    app.add_directive('mainmatter', MainMatter)
+    app.add_directive('backmatter', BackMatter)
     app.connect('autodoc-process-signature', resig)

but building still failed https://travis-ci.org/github/Pylons/pyramid/jobs/676546160#L412

/home/travis/build/Pylons/pyramid/.tox/docs/lib/python3.6/site-packages/pyramid/request.py:docstring of pyramid.request.Request.response:1:duplicate object description of pyramid.request.Request.response, other instance in api/request, use :noindex: for one of them

Makefile:105: recipe for target 'doctest' failed

without -W flag here is so many warning:

Warnings list

/mnt/data/coding/pyramid/src/pyramid/request.py:docstring of pyramid.request.Request.response:1: WARNING: duplicate object description of pyramid.request.Request.response, other instance in api/request, use :noindex: for one of them
/mnt/data/coding/pyramid/src/pyramid/request.py:docstring of pyramid.request.Request.session:1: WARNING: duplicate object description of pyramid.request.Request.session, other instance in api/request, use :noindex: for one of them

/mnt/data/coding/pyramid/src/pyramid/config/__init__.py:docstring of pyramid.config.Configurator:43: WARNING: term not in glossary: deployment settings
/mnt/data/coding/pyramid/src/pyramid/config/__init__.py:docstring of pyramid.config.Configurator.include:8: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/src/pyramid/config/__init__.py:docstring of pyramid.config.Configurator.scan:40: WARNING: term not in glossary: venusian
/mnt/data/coding/pyramid/src/pyramid/config/routes.py:docstring of pyramid.config.Configurator.add_route:1: WARNING: term not in glossary: Route predicate
/mnt/data/coding/pyramid/src/pyramid/config/settings.py:docstring of pyramid.config.Configurator.add_settings:1: WARNING: term not in glossary: deployment settings
/mnt/data/coding/pyramid/src/pyramid/config/settings.py:docstring of pyramid.config.Configurator.get_settings:1: WARNING: term not in glossary: deployment settings
/mnt/data/coding/pyramid/src/pyramid/config/views.py:docstring of pyramid.config.Configurator.add_accept_view_order:1: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/src/pyramid/config/__init__.py:docstring of pyramid.config.Configurator.setup_registry:1: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/src/pyramid/events.py:docstring of pyramid.events.subscriber:54: WARNING: term not in glossary: venusian
/mnt/data/coding/pyramid/src/pyramid/events.py:docstring of pyramid.events.subscriber:57: WARNING: term not in glossary: venusian
/mnt/data/coding/pyramid/src/pyramid/exceptions.py:docstring of pyramid.exceptions.ConfigurationError:1: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/src/pyramid/httpexceptions.py:docstring of pyramid.httpexceptions.HTTPForbidden:8: WARNING: term not in glossary: Forbidden View
/mnt/data/coding/pyramid/src/pyramid/httpexceptions.py:docstring of pyramid.httpexceptions.HTTPForbidden:25: WARNING: term not in glossary: Forbidden View
/mnt/data/coding/pyramid/venv/lib/python3.8/site-packages/translationstring/__init__.py:docstring of pyramid.i18n.TranslationString:1: WARNING: term not in glossary: translation string
/mnt/data/coding/pyramid/venv/lib/python3.8/site-packages/translationstring/__init__.py:docstring of pyramid.i18n.TranslationString:4: WARNING: term not in glossary: message identifier
/mnt/data/coding/pyramid/venv/lib/python3.8/site-packages/translationstring/__init__.py:docstring of pyramid.i18n.TranslationString:30: WARNING: term not in glossary: translation string
/mnt/data/coding/pyramid/venv/lib/python3.8/site-packages/translationstring/__init__.py:docstring of pyramid.i18n.TranslationString:35: WARNING: term not in glossary: translation context
/mnt/data/coding/pyramid/src/pyramid/i18n.py:docstring of pyramid.i18n.Localizer.pluralize:1: WARNING: term not in glossary: message identifier
/mnt/data/coding/pyramid/src/pyramid/i18n.py:docstring of pyramid.i18n.Localizer.translate:1: WARNING: term not in glossary: translation string
/mnt/data/coding/pyramid/docs/api/registry.rst:12: WARNING: term not in glossary: deployment settings
/mnt/data/coding/pyramid/docs/api/registry.rst:21: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/api/registry.rst:33: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/api/request.rst:347: WARNING: term not in glossary: localizer
/mnt/data/coding/pyramid/src/pyramid/response.py:docstring of pyramid.response.response_adapter:42: WARNING: term not in glossary: venusian
/mnt/data/coding/pyramid/src/pyramid/response.py:docstring of pyramid.response.response_adapter:45: WARNING: term not in glossary: venusian
/mnt/data/coding/pyramid/src/pyramid/scripting.py:docstring of pyramid.scripting.get_root:7: WARNING: term not in glossary: Request Factory
/mnt/data/coding/pyramid/src/pyramid/scripting.py:docstring of pyramid.scripting.prepare:6: WARNING: term not in glossary: Request Factory
/mnt/data/coding/pyramid/src/pyramid/view.py:docstring of pyramid.view.view_config:39: WARNING: term not in glossary: venusian
/mnt/data/coding/pyramid/src/pyramid/view.py:docstring of pyramid.view.view_config:42: WARNING: term not in glossary: venusian
/mnt/data/coding/pyramid/src/pyramid/wsgi.py:docstring of pyramid.wsgi.wsgiapp:22: WARNING: term not in glossary: Response
/mnt/data/coding/pyramid/docs/designdefense.rst:31: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/designdefense.rst:556: WARNING: term not in glossary: translation string
/mnt/data/coding/pyramid/docs/glossary.rst:1051: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/glossary.rst:933: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/glossary.rst:660: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/glossary.rst:847: WARNING: term not in glossary: translation string
/mnt/data/coding/pyramid/docs/glossary.rst:847: WARNING: term not in glossary: message catalog
/mnt/data/coding/pyramid/docs/glossary.rst:580: WARNING: term not in glossary: Response
/mnt/data/coding/pyramid/docs/glossary.rst:753: WARNING: term not in glossary: Traversal
/mnt/data/coding/pyramid/docs/glossary.rst:450: WARNING: term not in glossary: URL Dispatch
/mnt/data/coding/pyramid/docs/glossary.rst:553: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/glossary.rst:795: WARNING: term not in glossary: translation string
/mnt/data/coding/pyramid/docs/glossary.rst:795: WARNING: term not in glossary: localizer
/mnt/data/coding/pyramid/docs/narr/advconfig.rst:9: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/advconfig.rst:376: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/assets.rst:753: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/configuration.rst:57: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/configuration.rst:138: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/environment.rst:505: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/environment.rst:525: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/events.rst:64: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/extconfig.rst:23: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/extending.rst:70: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/firstapp.rst:201: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/firstapp.rst:245: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/hooks.rst:429: WARNING: term not in glossary: Request
/mnt/data/coding/pyramid/docs/narr/hybrid.rst:48: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/hybrid.rst:91: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/hybrid.rst:117: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/hybrid.rst:117: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/hybrid.rst:132: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/hybrid.rst:198: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/hybrid.rst:202: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/hybrid.rst:282: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/hybrid.rst:282: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/i18n.rst:32: WARNING: term not in glossary: translation string
/mnt/data/coding/pyramid/docs/narr/i18n.rst:99: WARNING: term not in glossary: translator
/mnt/data/coding/pyramid/docs/narr/i18n.rst:136: WARNING: term not in glossary: translation string
/mnt/data/coding/pyramid/docs/narr/i18n.rst:210: WARNING: term not in glossary: message catalog
/mnt/data/coding/pyramid/docs/narr/i18n.rst:221: WARNING: term not in glossary: message identifier
/mnt/data/coding/pyramid/docs/narr/i18n.rst:221: WARNING: term not in glossary: translation string
/mnt/data/coding/pyramid/docs/narr/i18n.rst:403: WARNING: term not in glossary: localizer
/mnt/data/coding/pyramid/docs/narr/i18n.rst:403: WARNING: term not in glossary: localizer
/mnt/data/coding/pyramid/docs/narr/i18n.rst:429: WARNING: term not in glossary: localizer
/mnt/data/coding/pyramid/docs/narr/i18n.rst:429: WARNING: term not in glossary: translation string
/mnt/data/coding/pyramid/docs/narr/i18n.rst:466: WARNING: term not in glossary: localizer
/mnt/data/coding/pyramid/docs/narr/i18n.rst:486: WARNING: term not in glossary: message identifier
/mnt/data/coding/pyramid/docs/narr/i18n.rst:497: WARNING: term not in glossary: translation string
/mnt/data/coding/pyramid/docs/narr/i18n.rst:564: WARNING: term not in glossary: localizer
/mnt/data/coding/pyramid/docs/narr/i18n.rst:615: WARNING: term not in glossary: translation string
/mnt/data/coding/pyramid/docs/narr/i18n.rst:819: WARNING: term not in glossary: message catalog
/mnt/data/coding/pyramid/docs/narr/i18n.rst:827: WARNING: term not in glossary: message catalog
/mnt/data/coding/pyramid/docs/narr/i18n.rst:888: WARNING: term not in glossary: localizer
/mnt/data/coding/pyramid/docs/narr/introspector.rst:618: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/muchadoabouttraversal.rst:25: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/muchadoabouttraversal.rst:34: WARNING: term not in glossary: Traversal
/mnt/data/coding/pyramid/docs/narr/paste.rst:29: WARNING: term not in glossary: deployment settings
/mnt/data/coding/pyramid/docs/narr/project.rst:597: WARNING: term not in glossary: Project
/mnt/data/coding/pyramid/docs/narr/project.rst:861: WARNING: term not in glossary: Package
/mnt/data/coding/pyramid/docs/narr/project.rst:903: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/project.rst:912: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/renderers.rst:6: WARNING: term not in glossary: Response
/mnt/data/coding/pyramid/docs/narr/renderers.rst:97: WARNING: term not in glossary: HTTP exception
/mnt/data/coding/pyramid/docs/narr/router.rst:59: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/security.rst:32: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/templates.rst:114: WARNING: term not in glossary: Response
/mnt/data/coding/pyramid/docs/narr/templates.rst:331: WARNING: term not in glossary: Response
/mnt/data/coding/pyramid/docs/narr/templates.rst:343: WARNING: term not in glossary: Response
/mnt/data/coding/pyramid/docs/narr/testing.rst:78: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/testing.rst:226: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/testing.rst:302: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/testing.rst:320: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/threadlocals.rst:61: WARNING: term not in glossary: Router
/mnt/data/coding/pyramid/docs/narr/threadlocals.rst:61: WARNING: term not in glossary: Router
/mnt/data/coding/pyramid/docs/narr/traversal.rst:12: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/traversal.rst:25: WARNING: term not in glossary: Traversal
/mnt/data/coding/pyramid/docs/narr/traversal.rst:37: WARNING: term not in glossary: Traversal
/mnt/data/coding/pyramid/docs/narr/traversal.rst:54: WARNING: term not in glossary: Traversal
/mnt/data/coding/pyramid/docs/narr/traversal.rst:88: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/traversal.rst:108: WARNING: term not in glossary: Router
/mnt/data/coding/pyramid/docs/narr/traversal.rst:108: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/traversal.rst:125: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/traversal.rst:140: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/traversal.rst:202: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/traversal.rst:202: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/traversal.rst:202: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/traversal.rst:251: WARNING: term not in glossary: Traversal
/mnt/data/coding/pyramid/docs/narr/traversal.rst:280: WARNING: term not in glossary: Router
/mnt/data/coding/pyramid/docs/narr/traversal.rst:280: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/traversal.rst:350: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/traversal.rst:403: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/traversal.rst:537: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/urldispatch.rst:19: WARNING: term not in glossary: Router
/mnt/data/coding/pyramid/docs/narr/urldispatch.rst:23: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/urldispatch.rst:37: WARNING: term not in glossary: Route configuration
/mnt/data/coding/pyramid/docs/narr/urldispatch.rst:425: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/urldispatch.rst:433: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/urldispatch.rst:604: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/urldispatch.rst:1270: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/urldispatch.rst:1270: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/urldispatch.rst:1380: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/urldispatch.rst:1385: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/viewconfig.rst:13: WARNING: term not in glossary: View lookup
/mnt/data/coding/pyramid/docs/narr/viewconfig.rst:13: WARNING: term not in glossary: View configuration
/mnt/data/coding/pyramid/docs/narr/viewconfig.rst:13: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/viewconfig.rst:58: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/viewconfig.rst:63: WARNING: term not in glossary: View predicate
/mnt/data/coding/pyramid/docs/narr/viewconfig.rst:63: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/viewconfig.rst:1027: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/viewconfig.rst:1117: WARNING: term not in glossary: view lookup
/mnt/data/coding/pyramid/docs/narr/views.rst:34: WARNING: term not in glossary: Request
/mnt/data/coding/pyramid/docs/narr/views.rst:41: WARNING: term not in glossary: Response
/mnt/data/coding/pyramid/docs/narr/views.rst:41: WARNING: term not in glossary: Response
/mnt/data/coding/pyramid/docs/narr/views.rst:55: WARNING: term not in glossary: Response
/mnt/data/coding/pyramid/docs/narr/views.rst:124: WARNING: term not in glossary: Response
/mnt/data/coding/pyramid/docs/narr/views.rst:124: WARNING: term not in glossary: Response
/mnt/data/coding/pyramid/docs/narr/views.rst:165: WARNING: term not in glossary: HTTP exception
/mnt/data/coding/pyramid/docs/narr/views.rst:178: WARNING: term not in glossary: http exception
/mnt/data/coding/pyramid/docs/narr/views.rst:248: WARNING: term not in glossary: Forbidden View
/mnt/data/coding/pyramid/docs/narr/zca.rst:86: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/zca.rst:151: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/zca.rst:151: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/zca.rst:151: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/narr/zca.rst:233: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/quick_tutorial/jinja2.rst:96: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/tutorials/wiki/basiclayout.rst:56: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/tutorials/wiki2/basiclayout.rst:48: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/whatsnew-1.0.rst:272: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/whatsnew-1.1.rst:91: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/whatsnew-1.2.rst:122: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/whatsnew-1.2.rst:189: WARNING: term not in glossary: deployment settings
/mnt/data/coding/pyramid/docs/whatsnew-1.2.rst:196: WARNING: term not in glossary: deployment settings
/mnt/data/coding/pyramid/docs/whatsnew-1.2.rst:203: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/whatsnew-1.2.rst:213: WARNING: term not in glossary: Configurator
/mnt/data/coding/pyramid/docs/whatsnew-1.3.rst:80: WARNING: term not in glossary: waitress

[stevepiercy]

Unless we want to pin to <3.0 (RTD uses 3.0.x), then this needs to be completed sooner than later, and backported to 1.10 and 1.9 branches to have future successful builds. Although there are many warnings, they are mostly repetitive due to omission of a few glossary entries. I've assigned this issue to myself.