From e5c55e68742fb2ce92103b0fd17109260ae08257 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Tue, 10 Nov 2026 15:36:29 -0700 Subject: [PATCH 1/2] quick doc fixes to improve rendering --- docs/api/authorization.rst | 12 ++++++------ docs/conf.py | 5 +++++ docs/narr/hooks.rst | 2 +- docs/whatsnew-1.8.rst | 2 +- docs/whatsnew-2.0.rst | 2 +- src/pyramid/config/testing.py | 2 +- src/pyramid/exceptions.py | 2 +- src/pyramid/renderers.py | 2 +- src/pyramid/util.py | 2 +- src/pyramid/view.py | 2 +- 10 files changed, 19 insertions(+), 14 deletions(-) diff --git a/docs/api/authorization.rst b/docs/api/authorization.rst index be040f0554..e11d0ab13a 100644 --- a/docs/api/authorization.rst +++ b/docs/api/authorization.rst @@ -11,7 +11,7 @@ .. autoclass:: ACLAuthorizationPolicy Constants ---------- +~~~~~~~~~ .. attribute:: Everyone @@ -57,22 +57,22 @@ Constants Moved from ``pyramid.security`` into ``pyramid.authorization``. Return Values -------------- +~~~~~~~~~~~~~ .. autoclass:: ACLDenied :members: msg .. automethod:: __new__ - .. versionadded:: 2.0 + .. versionadded:: 2.0 - Moved from ``pyramid.security`` into ``pyramid.authorization``. + Moved from ``pyramid.security`` into ``pyramid.authorization``. .. autoclass:: ACLAllowed :members: msg .. automethod:: __new__ - .. versionadded:: 2.0 + .. versionadded:: 2.0 - Moved from ``pyramid.security`` into ``pyramid.authorization``. + Moved from ``pyramid.security`` into ``pyramid.authorization``. diff --git a/docs/conf.py b/docs/conf.py index 6b644adc9b..7cd0cd5a66 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -116,6 +116,11 @@ def nothing(*arg): # unit titles (such as .. function::). add_module_names = False +# Show "add_view()" rather than "Configurator.add_view()" for API objects in +# the sidebar table of contents. The parents are already given by the nesting, +# and the fully qualified names are too long to fit in the sidebar. +toc_object_entries_show_parents = 'hide' + # The name of the Pygments (syntax highlighting) style to use. #pygments_style = book and 'bw' or 'tango' if book: diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 73a0143bf1..7e8513a6ab 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -1493,7 +1493,7 @@ method. For example: def __call__(self, context, request): return request.content_type == self.val -The constructor of an :class:`pyramid.interfaces.IPredicateFactory`` takes two arguments: ``val`` and ``info``. +The constructor of an :class:`pyramid.interfaces.IPredicateFactory` takes two arguments: ``val`` and ``info``. The ``val`` argument will be the argument passed to ``view_config`` (or ``add_view``). In the example above, it will be the string ``File``. The second argument, ``info``, will be an :class:`pyramid.interfaces.IPredicateInfo` instance created relative to the action configuring the predicate. diff --git a/docs/whatsnew-1.8.rst b/docs/whatsnew-1.8.rst index d6b58ced85..92d7248165 100644 --- a/docs/whatsnew-1.8.rst +++ b/docs/whatsnew-1.8.rst @@ -115,7 +115,7 @@ Minor Feature Additions earlier calls. See https://github.com/Pylons/pyramid/pull/2902 - Added a new ``callback`` option to - :meth:`pyramid.config.Configurator.set_default_csrf_options`` which + :meth:`pyramid.config.Configurator.set_default_csrf_options` which can be used to determine per-request whether CSRF checking should be enabled to allow for a mix authentication methods. Only cookie-based methods generally require CSRF checking. diff --git a/docs/whatsnew-2.0.rst b/docs/whatsnew-2.0.rst index eeaf065d84..b3b4f15f10 100644 --- a/docs/whatsnew-2.0.rst +++ b/docs/whatsnew-2.0.rst @@ -116,7 +116,7 @@ Deprecations - :class:`pyramid.authorization.ACLAuthorizationPolicy` - The ``effective_principals`` view and route predicates. -- Deprecated :func:`pyramid.security.principals_allowed_by_permission``. +- Deprecated :func:`pyramid.security.principals_allowed_by_permission`. This method continues to work with the deprecated :class:`pyramid.interfaces.IAuthorizationPolicy` interface but will not work with the new :class:`pyramid.interfaces.ISecurityPolicy`. See https://github.com/Pylons/pyramid/pull/3465 diff --git a/src/pyramid/config/testing.py b/src/pyramid/config/testing.py index 4ff858d89e..54009c9dd1 100644 --- a/src/pyramid/config/testing.py +++ b/src/pyramid/config/testing.py @@ -34,7 +34,7 @@ def testing_securitypolicy( :type userid: str :param identity: If provided, the policy's ``identity`` method will return this value. As a result, - :attr:`pyramid.request.Request.identity`` will have this value. + :attr:`pyramid.request.Request.identity` will have this value. :type identity: object :param permissive: If true, the policy will allow access to any user for any permission. If false, the policy will deny all access. diff --git a/src/pyramid/exceptions.py b/src/pyramid/exceptions.py index 9f19a4bb4d..6f61b8f378 100644 --- a/src/pyramid/exceptions.py +++ b/src/pyramid/exceptions.py @@ -41,7 +41,7 @@ class PredicateMismatch(HTTPNotFound): This exception subclasses the :class:`HTTPNotFound` exception for a specific reason: if it reaches the main exception handler, it should - be treated as :class:`HTTPNotFound`` by any exception view + be treated as :class:`HTTPNotFound` by any exception view registrations. Thus, typically, this exception will not be seen publicly. diff --git a/src/pyramid/renderers.py b/src/pyramid/renderers.py index 943fde3460..92a0851c0d 100644 --- a/src/pyramid/renderers.py +++ b/src/pyramid/renderers.py @@ -335,7 +335,7 @@ class JSONP(JSON): Once this renderer is registered via :meth:`~pyramid.config.Configurator.add_renderer` as above, you can use ``jsonp`` as the ``renderer=`` parameter to ``@view_config`` or - :meth:`pyramid.config.Configurator.add_view``: + :meth:`pyramid.config.Configurator.add_view`: .. code-block:: python diff --git a/src/pyramid/util.py b/src/pyramid/util.py index c71528a493..288867c12f 100644 --- a/src/pyramid/util.py +++ b/src/pyramid/util.py @@ -464,7 +464,7 @@ def add(self, name, val, after=None, before=None): any other hashable object, the ``val`` should be the sortable (doesn't need to be hashable). ``after`` and ``before`` represents the name of one of the other sortables (or a sequence of such named) or one of the - special sentinel values :attr:`pyramid.util.FIRST`` or + special sentinel values :attr:`pyramid.util.FIRST` or :attr:`pyramid.util.LAST` representing the first or last positions respectively. ``FIRST`` and ``LAST`` can also be part of a sequence passed as ``before`` or ``after``. A sortable should not be added diff --git a/src/pyramid/view.py b/src/pyramid/view.py index 1541cdb230..ce016a6971 100644 --- a/src/pyramid/view.py +++ b/src/pyramid/view.py @@ -715,7 +715,7 @@ def invoke_exception_view( A boolean indicating whether the original error should be reraised if a :term:`response` object could not be created. If ``False`` - then an :class:`pyramid.httpexceptions.HTTPNotFound`` exception + then an :class:`pyramid.httpexceptions.HTTPNotFound` exception will be raised. Default: ``False``. If a response is generated then ``request.exception`` and From 3da217a56ac31d0a0ca4ce9d152fab9631134538 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Tue, 10 Nov 2026 15:40:41 -0700 Subject: [PATCH 2/2] add changelog for #3834 --- CHANGES.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGES.rst b/CHANGES.rst index f3c5f223cb..83b35d8a64 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -19,3 +19,5 @@ Deprecations Documentation Changes --------------------- +- Improve rendering of API Documentation by removing the prefixes to APIs in the sidebar. + See https://github.com/Pylons/pyramid/pull/3834