From 07d59c7410b4cfff13dc644a3da3dcb3574ad951 Mon Sep 17 00:00:00 2001 From: Subham Sangwan Date: Sun, 9 Nov 2025 12:27:02 +0530 Subject: [PATCH] Fix documentation build warnings (#1484) This commit addresses all the warnings reported when running `tox -e docs`: 1. Fixed title underlines in settings.rst that were too short: - OIDC_RP_INITIATED_LOGOUT_ENABLED - OIDC_RP_INITIATED_LOGOUT_STRICT_REDIRECT_URIS - OIDC_RP_INITIATED_LOGOUT_ACCEPT_EXPIRED_TOKENS 2. Fixed unexpected indentation in contributing.rst by adding a colon before the code block 3. Fixed unexpected indentation in oidc.rst by converting inline code blocks (::) to proper code-block directives at lines 292 and 336 4. Fixed unknown interpreted text role ':openid:' in AbstractIDToken docstring by replacing it with plain text reference to OpenID Connect specification 5. Fixed duplicate object descriptions between views/details.rst and views/mixins.rst by adding :noindex: directive to details.rst 6. Fixed code block lexer warning in management_commands.rst by changing the language from 'sh' to 'text' for the usage output --- docs/contributing.rst | 2 +- docs/management_commands.rst | 2 +- docs/oidc.rst | 10 ++++++++-- docs/settings.rst | 6 +++--- docs/views/details.rst | 1 + oauth2_provider/models.py | 2 +- 6 files changed, 15 insertions(+), 8 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index a633419e2..98afa3f62 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -258,7 +258,7 @@ For test writers this means any test must either: - when using pytest's `django_db` mark, define it like this: `@pytest.mark.django_db(databases=retrieve_current_databases())` -In test code, anywhere the database is referenced the Django router needs to be used exactly like the package's code. +In test code, anywhere the database is referenced the Django router needs to be used exactly like the package's code: .. code-block:: python diff --git a/docs/management_commands.rst b/docs/management_commands.rst index 0a3f1bda0..3853b3289 100644 --- a/docs/management_commands.rst +++ b/docs/management_commands.rst @@ -32,7 +32,7 @@ createapplication The ``createapplication`` management command provides a shortcut to create a new application in a programmatic way. -.. code-block:: sh +.. code-block:: text usage: manage.py createapplication [-h] [--client-id CLIENT_ID] [--user USER] [--redirect-uris REDIRECT_URIS] diff --git a/docs/oidc.rst b/docs/oidc.rst index 1669a00d4..f462682e9 100644 --- a/docs/oidc.rst +++ b/docs/oidc.rst @@ -288,7 +288,10 @@ mapping a claim name to claim data:: The second form gets no request object, and should return a dictionary mapping a claim name to a callable, accepting a request and producing -the claim data:: +the claim data: + +.. code-block:: python + class CustomOAuth2Validator(OAuth2Validator): # Extend the standard scopes to add a new "permissions" scope # which returns a "permissions" claim: @@ -332,7 +335,10 @@ For example, a ``given_name`` claim is only returned if the ``profile`` scope wa To change the list of claims and which scopes result in their being returned, override ``oidc_claim_scope`` with a dict keyed by claim with a value of scope. -The following example adds instructions to return the ``foo`` claim when the ``bar`` scope is granted:: +The following example adds instructions to return the ``foo`` claim when the ``bar`` scope is granted: + +.. code-block:: python + class CustomOAuth2Validator(OAuth2Validator): oidc_claim_scope = OAuth2Validator.oidc_claim_scope oidc_claim_scope.update({"foo": "bar"}) diff --git a/docs/settings.rst b/docs/settings.rst index 9c71bb2a8..e70d300c9 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -354,7 +354,7 @@ If unset, the default location is used, eg if ``django-oauth-toolkit`` is mounted at ``/o/``, it will be ``/o/userinfo/``. OIDC_RP_INITIATED_LOGOUT_ENABLED -~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Default: ``False`` When is set to ``False`` (default) the `OpenID Connect RP-Initiated Logout `_ @@ -369,13 +369,13 @@ Whether to always prompt the :term:`Resource Owner` (End User) to confirm a logo :term:`Client` (Relying Party). If it is disabled the :term:`Resource Owner` (End User) will only be prompted if required by the standard. OIDC_RP_INITIATED_LOGOUT_STRICT_REDIRECT_URIS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Default: ``False`` Enable this setting to require `https` in post logout redirect URIs. `http` is only allowed when a :term:`Client` is `confidential`. OIDC_RP_INITIATED_LOGOUT_ACCEPT_EXPIRED_TOKENS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Default: ``True`` Whether expired ID tokens are accepted for RP-Initiated Logout. The Tokens must still be signed by the OP and otherwise valid. diff --git a/docs/views/details.rst b/docs/views/details.rst index 07d4f6a90..bc145671f 100644 --- a/docs/views/details.rst +++ b/docs/views/details.rst @@ -17,6 +17,7 @@ inside their Django applications. .. automodule:: oauth2_provider.views.mixins :members: + :noindex: Base ---- diff --git a/oauth2_provider/models.py b/oauth2_provider/models.py index a76db37c0..5dfedb088 100644 --- a/oauth2_provider/models.py +++ b/oauth2_provider/models.py @@ -557,7 +557,7 @@ class Meta(AbstractRefreshToken.Meta): class AbstractIDToken(models.Model): """ An IDToken instance represents the actual token to - access user's resources, as in :openid:`2`. + access user's resources, as defined in the OpenID Connect specification. Fields: