search

sphinx-doc / sphinxcontrib-django

This is a sphinx extension which improves the documentation of Django apps.
https://pypi.org/project/sphinxcontrib-django/
Apache License 2.0
43 stars 25 forks source link

Fix readthedocs build #58

Closed timobrembeck closed 1 year ago

timobrembeck commented 1 year ago

Short description

codecov-commenter commented 1 year ago

Codecov Report

Merging #58 (84cfda6) into main (91d3f83) will not change coverage. The diff coverage is 100.00%.

@@            Coverage Diff            @@
##              main       #58   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           10        10           
  Lines          328       328           
=========================================
  Hits           328       328
Files Coverage Δ
sphinxcontrib_django/__init__.py 100.00% <100.00%> (ø)
sphinxcontrib_django/docstrings/__init__.py 100.00% <100.00%> (ø)
sphinxcontrib_django/docstrings/classes.py 100.00% <100.00%> (ø)
sphinxcontrib_django/docstrings/field_utils.py 100.00% <100.00%> (ø)
sphinxcontrib_django/roles.py 100.00% <100.00%> (ø)

:mega: We’re building smart automated test selection to slash your CI/CD build times. Learn more

timobrembeck commented 1 year ago

@WhyNotHugo Do you have an idea why these changes are necessary to fix the documentation build?

Before, the type hints caused a few reference target not found errors:

/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-django/envs/bugfix-readthedocs/lib/python3.11/site-packages/sphinxcontrib_django/docstrings/__init__.py:docstring of sphinxcontrib_django.docstrings.autodoc_skip:1: WARNING: py:class reference target not found: Sphinx
/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-django/envs/bugfix-readthedocs/lib/python3.11/site-packages/sphinxcontrib_django/docstrings/__init__.py:docstring of sphinxcontrib_django.docstrings.autodoc_skip:1: WARNING: py:class reference target not found: Options
/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-django/envs/bugfix-readthedocs/lib/python3.11/site-packages/sphinxcontrib_django/docstrings/__init__.py:docstring of sphinxcontrib_django.docstrings.improve_docstring:1: WARNING: py:class reference target not found: Sphinx
/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-django/envs/bugfix-readthedocs/lib/python3.11/site-packages/sphinxcontrib_django/docstrings/__init__.py:docstring of sphinxcontrib_django.docstrings.improve_docstring:1: WARNING: py:class reference target not found: Options
/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-django/envs/bugfix-readthedocs/lib/python3.11/site-packages/sphinxcontrib_django/docstrings/__init__.py:docstring of sphinxcontrib_django.docstrings.setup:1: WARNING: py:class reference target not found: Sphinx
/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-django/envs/bugfix-readthedocs/lib/python3.11/site-packages/sphinxcontrib_django/docstrings/__init__.py:docstring of sphinxcontrib_django.docstrings.setup_django:1: WARNING: py:class reference target not found: Sphinx
/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-django/envs/bugfix-readthedocs/lib/python3.11/site-packages/sphinxcontrib_django/docstrings/__init__.py:docstring of sphinxcontrib_django.docstrings.setup_django:1: WARNING: py:class reference target not found: Config
/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-django/envs/bugfix-readthedocs/lib/python3.11/site-packages/sphinxcontrib_django/docstrings/field_utils.py:docstring of sphinxcontrib_django.docstrings.field_utils.get_field_type:1: WARNING: py:class reference target not found: django.db.models.fields.Field
/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-django/envs/bugfix-readthedocs/lib/python3.11/site-packages/sphinxcontrib_django/docstrings/field_utils.py:docstring of sphinxcontrib_django.docstrings.field_utils.get_field_verbose_name:1: WARNING: py:class reference target not found: django.db.models.fields.Field
/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-django/envs/bugfix-readthedocs/lib/python3.11/site-packages/sphinxcontrib_django/docstrings/field_utils.py:docstring of sphinxcontrib_django.docstrings.field_utils.get_model_from_string:1: WARNING: py:class reference target not found: django.db.models.fields.Field
/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-django/envs/bugfix-readthedocs/lib/python3.11/site-packages/sphinxcontrib_django/docstrings/field_utils.py:docstring of sphinxcontrib_django.docstrings.field_utils.get_model_from_string:1: WARNING: py:class reference target not found: django.db.models.base.Model
/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-django/envs/bugfix-readthedocs/lib/python3.11/site-packages/sphinxcontrib_django/docstrings/classes.py:docstring of sphinxcontrib_django.docstrings.classes.add_db_table_name:1: WARNING: py:class reference target not found: django.db.models.base.Model
/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-django/envs/bugfix-readthedocs/lib/python3.11/site-packages/sphinxcontrib_django/docstrings/classes.py:docstring of sphinxcontrib_django.docstrings.classes.add_model_parameters:1: WARNING: py:class reference target not found: django.db.models.fields.Field
/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-django/envs/bugfix-readthedocs/lib/python3.11/site-packages/sphinxcontrib_django/docstrings/classes.py:docstring of sphinxcontrib_django.docstrings.classes.improve_form_docstring:1: WARNING: py:class reference target not found: django.forms.forms.Form
/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-django/envs/bugfix-readthedocs/lib/python3.11/site-packages/sphinxcontrib_django/docstrings/classes.py:docstring of sphinxcontrib_django.docstrings.classes.improve_model_docstring:1: WARNING: py:class reference target not found: django.db.models.base.Model

And afterwards, the doc build succeeds...

WhyNotHugo commented 1 year ago

I think this can be fixed by adding:

from __future__ import annotations

To the files with annotations where it is missing.

WhyNotHugo commented 1 year ago

Ruff has a setting/lint to include this import in all files with content. I can include this if https://github.com/edoburu/sphinxcontrib-django/pull/50 seems okay.

timobrembeck commented 1 year ago

I think this can be fixed by adding:

from __future__ import annotations

To the files with annotations where it is missing.

Hmm, this line was present in all files with type annotations, so this does not seem to be the reason :thinking:

Ruff has a setting/lint to include this import in all files with content. I can include this if https://github.com/edoburu/sphinxcontrib-django/pull/50 seems okay.

I think I'm going to merge this PR now to fix the doc build, if you find a way to have the short concise types without breaking the doc build, feel free to revert my changes in a future PR :grin: