Repository navigation
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. 🚀 New features to boost your workflow:
|
|
@WilliamJamieson , please rebase to pick up devdeps fixes. Thanks!
Might be surprising for downstream packages. Are you sure?! |
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? |
|
I just ran into this again in a different project. Can we merge it 😆 |
astrofrog
left a comment
astrofrog
left a comment
There was a problem hiding this comment.
Approving as seems ok to me, but see small comment below. Also @WilliamJamieson can you confirm the astropy docs build fine with this PR?
| # elif typ == 'attribute' and documenter.objtype == 'property': | ||
| # # In Sphinx 2.0 and above, properties have a separate | ||
| # # objtype, but we treat them the same here. | ||
| # items.append(name) |
|
A astropy doc build is running here: astropy/astropy#17919 |
|
The astropy RTD build passed with the default option. I think we can merge this, and once a few packages are using this on an opt-in basis successfully we can consider toggling the default? |
|
Someone will have to do new release. ;) |
|
If no one does it, I can do one in the evening. |
5 participants
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.