Open aminalaee opened 2 years ago
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:
^ 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?
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:
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:
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
throughmkdocstrings
and if relevant, please attach a screenshot.System (please complete the following information):
pytkdocs
version [e.g. 0.2.1]Additional context Add any other context about the problem here.