Add option to document properties using autoproperty instead of autoattribute #197
Conversation
|
To see the difference, before these changes: |
|
Might wanna wait for #196 to make sure this actually passes with sphinx-dev |
| public_properties, all_properties = \ | ||
| get_members_class(obj, 'property', | ||
| include_base=include_base) | ||
| if properties_are_attributes: | ||
| ns['attributes'].extend(public_properties) | ||
| ns['all_attributes'].extend(all_properties) | ||
| else: | ||
| ns['properties'] = public_properties | ||
| ns['all_properties'] = all_properties |
There was a problem hiding this comment.
This is the real change.
|
Want to revisit #134 after this, too and then we can cut a release? |
|
I am pro making this new behavior the default. @WilliamJamieson said to me that automodapi predates autoproperty in sphinx. I see no good reason why we should use this everywhere. |
Codecov ReportAttention: Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #197 +/- ##
==========================================
- Coverage 90.29% 90.05% -0.25%
==========================================
Files 30 31 +1
Lines 1206 1227 +21
==========================================
+ Hits 1089 1105 +16
- Misses 117 122 +5 ☔ View full report in Codecov by Sentry. |
|
@WilliamJamieson , please rebase to pick up devdeps fixes. Thanks!
Might be surprising for downstream packages. Are you sure?! |
WilliamJamieson
force-pushed
the
autoproperty
branch
from
77be352 to
09aeffb
Compare
Sure things change when you upgrade packages. I think this is a straight upgrade, with no real downside other than "different". If we want to we could make it throw a warning until someone explicitly sets the config flag? |
|
Given @eteq originally wrote this and @astrofrog then patched it (9 years ago!), maybe they have opinions? If not, maybe at least a draft PR to astropy with this branch to compare before merge? |
Currently attributes and properties are treated the same by
automodapiwhen it comes to generating documentation. This is problematic if one wants to do things like have the return type of apropertytype hint to be included in the documentation. Theautopropertydirective can do this, where as theautoattributecannot.This PR adds the config option
automodsumm_properties_are_attributeswhich whenTrue(the default) treats all properties like they are attributes and whenFalsetreats them using theautopropertydirective.