Closed WhyNotHugo closed 3 months ago
I'd like to see if this fixes the issues mentioned in https://github.com/sphinx-doc/sphinxcontrib-django/pull/58#issuecomment-1736156596
All modified and coverable lines are covered by tests :white_check_mark:
Project coverage is 100.00%. Comparing base (
f4dfbbd
) to head (cbba87e
). Report is 6 commits behind head on main.
:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.
Building docs fails with:
/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-django/envs/61/lib/python3.11/site-packages/sphinxcontrib_django/docstrings/attributes.py:docstring of sphinxcontrib_django.docstrings.attributes.get_field_details:1: WARNING: py:class reference target not found: django.db.models.fields.Field
I think that this means that the class django.db.models.fields.Field
isn't documented so a link can't be added to it. But I'm not sure if this is the actual cause of the failure.
I think that this means that the class
django.db.models.fields.Field
isn't documented so a link can't be added to it. But I'm not sure if this is the actual cause of the failure.
Yes, the underlying issue is that Django documents the Field
class as part of the django.db.models
module and not django.db.models.fields
:
https://docs.djangoproject.com/en/4.2/ref/models/fields/#django.db.models.Field
This is also a part why this sphinx extension was created in the first place - it deals with such inconsistencies and monkeypatches the module path to its new location:
I'm not sure about this, but maybe the monkeypatch gets bypassed if the module is imported directly from its source?
I'm not sure about this, but maybe the monkeypatch gets bypassed if the module is imported directly from its source?
I don't think this code ever gets executed when type checking, right?
I'm not sure about this, but maybe the monkeypatch gets bypassed if the module is imported directly from its source?
I don't think this code ever gets executed when type checking, right?
Indeed, but type checking is not the problem, the doc build is. And during doc build, the monkeypatch should be executed, but somehow it does not apply to the stuff that sphinx is extracting from the type hints? :thinking:
@WhyNotHugo And just because I could need this for another project:
Do you know a tool to automatically convert the :type my_argument: str
docstrings to the def func(my_argument: str)
syntax? Or did you do this manually in your PRs?
To me, it sounds like a task that could be automated, but I did not find a good tool for this except https://github.com/tox-dev/sphinx-autodoc-typehints which does not seem to be able to write the result back into the Python source files?
Ah, but maybe can the extension sphinx_autodoc_typehints
help to fix our problem here?
I mean it has the configuration option typehints_fully_qualified
which is False
by default (which is want we want, right?)...
Do you know a tool to automatically convert the :type my_argument: str docstrings to the def func(my_argument: str) syntax? Or did you do this manually in your PRs?
I did it manually. A tool that does this automatically would be superb.
To me, it sounds like a task that could be automated, but I did not find a good tool for this except https://github.com/tox-dev/sphinx-autodoc-typehints which does not seem to be able to write the result back into the Python source files?
I don't understand what this does. Sphinx already shows the types from type hints in the function signature by default. Example: https://django-afip.readthedocs.io/en/latest/api.html#django_afip.clients.get_client
Apparently CI failed because codecov was down.
Short description
Add type annotations to all non-test code.
Also configure
ruff
to complain loudly if new code is missing annotations.