fix: tooltips for class docstrings, whitespace issues

[koeaw]

• fixes linebreaks between text and HTML tags caused by templatetag
• checks for existence of proper docstring for classes (see PEP 257) instead of falling back on class definition

References:
https://peps.python.org/pep-0257/

[github-actions]

Thanks for your contribution! ⚠️ there seems to be a problem with your commit messages - they should adhere to the https://conventionalcommits.org specification. Please fix that!

[github-actions]

Thanks for your contribution! ⚠️ there seems to be a problem with your commit messages - they should adhere to the https://conventionalcommits.org specification. Please fix that!

[koeaw]

That link in the bot message is broken (... and I dunno why it doesn't like the formatting of my commit message).

Edit: ah, line length, got it.

[b1rger]

That link in the bot message is broken

yeah, I think I'll turn of the commenting - its rather annoying and the check output is probably enough as feedback

[koeaw]

Hm, hold on, still need to check something...

[koeaw]

... Well, that docstring check is rather useless, oups.

[koeaw]

The original PR description is outdated after a refactor and force push and/but this is still set to draft because:

• I hadn't considered the ramifications of my proposed CSS change on the placement of the "Create new" button on entity (list) pages (side note: button text could be shortened to "Create"),
• I had to give up tracking down how model.__doc__ is constructed when there is no docstring due to time constraints, so it's possible there is an easier/more elegant way to check for & exclude the not-so-helpful fallback.

[b1rger]

I had to give up tracking down how model.__doc__ is constructed when there is no docstring due to time constraints, so it's possible there is an easier/more elegant way to check for & exclude the not-so-helpful fallback.

https://github.com/django/django/blob/b287af5dc954628d4b336aefc5027b2edceee64b/django/db/models/base.py#L399

[koeaw]

I had to give up tracking down how model.__doc__ is constructed when there is no docstring due to time constraints, so it's possible there is an easier/more elegant way to check for & exclude the not-so-helpful fallback.

https://github.com/django/django/blob/b287af5dc954628d4b336aefc5027b2edceee64b/django/db/models/base.py#L399

Thank you!

@birger I wanted to tag you anyway because while I don't consider this finished yet/was expecting to work on this more, as per my previous comment, please let me know if you have any notes/feedback (if not a proper review yet). Just had to get that earlier update out of the way.

[b1rger]

please let me know if you have any notes/feedback

I would put the logic of "calculating" the docstring into the class - either the AbstractEntity, but we might even use this for non entity models, so RootObject might make more sense. For example something like this:

@classmethod
@property
def description(cls):
    return cls.__doc__ 

That way we don't have to add it to the context, because a ListView has access to the model class via the queryset anyway - and in the template we can simply use {{ object_list.model.description }}. There is one problem though, the class_definition templatetag "filters" the context and only passes the two variables in:

apis-core-rdf/apis_core/apis_metainfo/templatetags/apis_metainfo_extras.py

Line 7 in 8a937c2

@register.inclusion_tag("apis_metainfo/tags/class_definition.html", takes_context=True)

I think the whole vodoo with the values should be removed from that templatetag. But if we do that, then the whole templatetag becomes unnecesarry, and then the question is, why not add a second classmethod classname and simply replace the whole templatetag with <abbr title="{{ object_list.model.description }}">{{ object_list.model.classname }}</abbr> in the generic_list.html template itself... (the class_definition templatetag isn't being used anywhere else, afaics)

(updated after hitting submit too early...)

[b1rger]

The issue this PR tries to fix was fixed by using the generic app for the entities, so I think this can be closed?