[BUG] Wrong docstrings for attribute when aliased from another class

[aminalaee]

Describe the bug As you can see here: https://github.com/aminalaee/sqladmin/blob/main/sqladmin/models.py#L358 We have defined a member to be equal to an external third-party class:

class X:
     form_base_class = wtforms.Form
     """Some docstrings"""

When this class is parsed the parser follows the docstrings in the third-party package and doesn't show the docstrings defined in my docs:

https://aminalaee.github.io/sqladmin/api_reference/model_admin/#sqladmin.models.ModelAdmin.form_base_class

I think either we shouldn't allow this to happen or there should be an option to control this.

As a workaround we found that we can try mkdocstrings-python package but that doesn't follow the members attribute we set and shows unwanted members:

https://github.com/aminalaee/sqladmin/pull/106

To Reproduce It's already in the description.

Expected behavior

Screenshots If you are using pytkdocs through mkdocstrings and if relevant, please attach a screenshot.

System (please complete the following information):

• pytkdocs version [e.g. 0.2.1]
• Python version: [e.g. 3.8]
• OS: [Windows/Linux]

Additional context Add any other context about the problem here.

[dwreeves]

Two more bits of additional context.

---

(1.)

the design pattern of aliasing a class definition as a class variable can be seen in a few projects that use Sphinx docs, such as:

• Flask-Admin (example uses custom docstring for the aliased class):
  • source: https://github.com/flask-admin/flask-admin/blob/89b425b01450405b04fc67d4dad18f2820996e87/flask_admin/model/base.py#L537
  • Sphinx docs: https://flask-admin.readthedocs.io/en/latest/api/mod_model/#flask_admin.model.BaseModelView.form_base_class
• Flask (example does not use custom docstring for the aliased class):
  • source: https://github.com/pallets/flask/blob/c9a1f7ad6545c9cc27c41c385f1d4cd9c7cf1a98/src/flask/app.py#L197
  • Sphinx docs: https://flask.palletsprojects.com/en/2.0.x/api/?highlight=request_class#flask.Flask.request_class

^ So personally, I was expecting behavior similar to this as the default.

---

(2.)

Maybe it is possible that @aminalaee disagrees with me, but as far as I am concerned, it is unclear whether the true problem is (A) that pytkdocs doesn't override and obj's .__doc__ when there's a docstring below an attribute, or (B) that python-mkdocstrings, which uses griffe, doesn't have a members attribute (as already mentioned by Amin, griffe resolves the docstring properly whereas pytkdocs does not).

As far as I can tell, implementing a solution to either 1 of the 2 problems above would seem to work for the sqladmin documentation?

[pawamoy]

Hi, thanks for the report. That's a very good understanding of the current situation. Griffe and the new handler will definitely support members. In the meantime, it's probably possible to fix pytkdocs so that it uses the docstring below an assignment even if the value of the assignment is an object with a __doc__ attribute. This won't be a top priority to me so a PR would be welcome :smile: