Fix documentation build warnings#1648
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
brianhelba
force-pushed
the
doc-warning
branch
2 times, most recently
from
b98ac8f to
890f2cb
Compare
|
@dopry Please take a look. |
There was a problem hiding this comment.
Pull request overview
Reduces Sphinx documentation build warnings by cleaning up references, headings, and code-block directives across the docs.
Changes:
- Replaced/updated a model docstring reference to a concrete OpenID Connect spec URL.
- Removed the standalone
mixinsviews doc and adjusted views documentation structure/links. - Fixed multiple reStructuredText formatting issues (headings, blank lines, code-block language).
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| oauth2_provider/models.py | Updates the ID Token docstring to link directly to the OIDC specification section. |
| docs/views/views.rst | Removes mixins from the views toctree. |
| docs/views/mixins.rst | Deletes the dedicated mixins page. |
| docs/views/details.rst | Adds an explicit mixins reference label before the Mixins section. |
| docs/views/class_based.rst | Updates the mixins cross-reference to use :ref:. |
| docs/settings.rst | Fixes heading underline lengths for multiple OIDC settings. |
| docs/oidc.rst | Adds blank lines before literal blocks to satisfy rst/Sphinx formatting. |
| docs/management_commands.rst | Uses a more appropriate code-block:: console directive and trims trailing whitespace. |
| docs/contributing.rst | Adds blank lines around code blocks/lists to satisfy rst/Sphinx formatting. |
| docs/conf.py | Updates Django intersphinx URL to the current HTTPS docs domain. |
|
Just applied suggestions from Copilot. Both were valid. |
| :maxdepth: 2 | ||
|
|
||
| function_based | ||
| class_based |
There was a problem hiding this comment.
@brianhelba it would be nice to preserve those links. Can you look into that?
brianhelba
force-pushed
the
doc-warning
branch
2 times, most recently
from
0a3fc49 to
4d23437
Compare
|
I've just rebased this on top of #1620, which fixed a number of the issues originally in this PR. However, there are still some improvements remaining in this PR. @dopry I've responded to the feedback by moving and consolidating the mixins docs, but preserving the old page as a stub. Please take a look. |
|
@dopry Ping. This one is ready for final review and merge. |
| .. automodule:: oauth2_provider.views.mixins | ||
| :members: | ||
| The mixins documentation has moved to the :ref:`mixins` section in | ||
| :doc:`details`. |
There was a problem hiding this comment.
:doc:details`` likely points to a non-existent document (Sphinx :doc: expects a docname from the docs root). Since the target file is `docs/views/details.rst` (docname `views/details`), update this link to reference `views/details` (optionally with custom link text) so the stub page doesn’t introduce an `unknown document` warning.
| :doc:`details`. | |
| :doc:`views/details`. |
There was a problem hiding this comment.
@brianhelba can you confirm whether this is valid feedback or not?
Fixes as many Sphinx warnings as possible.
latestbuild.Checklist
CHANGELOG.mdupdated (only for user relevant changes)AUTHORS