Add missing type annotations and require them in new code

[WhyNotHugo]

Short description

Add type annotations to all non-test code.

Also configure ruff to complain loudly if new code is missing annotations.

[WhyNotHugo]

I'd like to see if this fixes the issues mentioned in #58 (comment)

[codecov]

Codecov Report

All modified lines are covered by tests ✅

Comparison is base (f4dfbbd) 100.00% compared to head (cbba87e) 100.00%.

Additional details and impacted files

@@            Coverage Diff            @@
##              main       #61   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           10        10           
  Lines          328       333    +5     
=========================================
+ Hits           328       333    +5     

Files	Coverage Δ
sphinxcontrib_django/docstrings/attributes.py	100.00% <100.00%> (ø)
sphinxcontrib_django/docstrings/config.py	100.00% <100.00%> (ø)
sphinxcontrib_django/docstrings/data.py	100.00% <100.00%> (ø)
sphinxcontrib_django/docstrings/methods.py	100.00% <100.00%> (ø)
sphinxcontrib_django/docstrings/patches.py	100.00% <100.00%> (ø)

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[WhyNotHugo]

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.

[timobrembeck]

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:

sphinxcontrib-django/sphinxcontrib_django/docstrings/patches.py

Line 90 in 72705c6

module_class.__module__ = parent_module_str

I'm not sure about this, but maybe the monkeypatch gets bypassed if the module is imported directly from its source?

[WhyNotHugo]

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?

[timobrembeck]

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? 🤔

[timobrembeck]

@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?

[timobrembeck]

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?)...

[WhyNotHugo]

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

[WhyNotHugo]

Apparently CI failed because codecov was down.

[timobrembeck]

Ahh, I found the culprit:
The patches are not correctly applied, because during docbuild, only the sphinxcontrib_django.roles extension is enabled:

sphinxcontrib-django/docs/conf.py

Line 28 in f4dfbbd

"sphinxcontrib_django.roles",

This means the patches are completely unused for our own docs. And there is no easy way to enable them without refactoring the structure of the extension, because the sphinxcontrib_django.docstrings extension needs Django settings and cannot be used without a standalone Django installation.
But I guess it makes sense to extract the patches from there, since patches are also relevant for Django library documentations, not only for Django applications.
I will refactor the structure of the extension first and then revisit this PR later!