Comments (5)
@minrk wrote in #28 (comment):
I think it's a valid goal to present the option to export only the configurable options, and not the Python API of a class. I'm not saying autoconfigurable without members is necessarily the right signature, but that output should be an option.
I agree, we should have a way to expose all traitlets members.
In my mind, we should provide a new configuration option, such as :config-members:
to emit all traits with .config(True)
. This kind of API should probably allow us to distinguish between class specific configuration options and inherited config options as well.
from autodoc-traits.
I think :config-members:
makes sense. I'm not certain what its inputs or defaults should be. I think we have a few questions to answer, that should clear it up:
- what does it look like to request all config on the current class, but not inherited config?
- what does it look like to request all config inherited by the current class (the default behavior before #28)?
- what does it look like to include only specific (or all minus specific) config members, a la the existing
:members:
or:exclude-members:
? - what does
autoconfigurable: Class
with no options given do by default (presumably it should be different fromautoclass: Class
for the same class. I'd say probably include the 'default' of all inherited or just current class config, with a slight inclination toward preserving current behavior unless there's a good reason to do something different).
Do we also need to think about non-config trait members, or leave that to the regular autoclass behavior with members, etc.? It seems like the existing behavior on autoclass with the trait-documenter works for that?
from autodoc-traits.
- what does it look like to request all config inherited by the current class (the default behavior before #28)?
It remains the default, its not changed! I'm updating the docs example to clarify that right now!
I'll reflect further later on other notes!
from autodoc-traits.
- what does it look like to request all config on the current class, but not inherited config?
- I suggest a boolean
:no-inherited-config-members:
option to resolve this is we want this feature, but we currently don't support it.
- what does it look like to include only specific (or all minus specific) config members, a la the existing :members: or :exclude-members:?
- Following #28, it is possible to use
:exclude-members:
to exclude config members. - We currently don't provide an option to specify specific config members to list. If the feature is merited to introduce I suggest we introduce
:config-members:
to provide a list of such config members. Where leaving it empty should then mean the same as the default behavior, which is to include all config members.
- what does
autoconfigurable: Class
with no options given do by default (presumably it should be different fromautoclass: Class
for the same class. I'd say probably include the 'default' of all inherited or just current class config, with a slight inclination toward preserving current behavior unless there's a good reason to do something different).
- Agree, let's preserve the default behavior. The default behavior is to present all traits, but no non-traits members.
Summary
Possible new features, as options to the autoconfigurable
directive.
:no-inherited-config-members:
, to omit inherited config members:config-members: <list>
, to specify only specific config members to list
Existing functionality (after #28):
:exclude-members:
, also functional for config members
from autodoc-traits.
Great summary!
I suggest a boolean :no-inherited-config-members: option to resolve this is we want this feature, but we currently don't support it.
👍 I think folks don't usually want to exclude inherited config, which may be why nobody's asked for this. No pressure to implement it, but good to document that we can't do it now, and know what it should look like if we do. It may make sense to stop at a particular class, rather than a bool.
The default behavior is to present all traits, but no non-traits members.
to be precise, all configurable traits, not all traits. I think there's still room for improving how we treat non-config trait members.
We currently don't provide an option to specify specific config members to list.
Why doesn't :members:
work for this, if :exclude-members:
does?
from autodoc-traits.
Related Issues (12)
- Add a summary of how it works in the readme HOT 3
- Autoregister sphinx.ext.autodoc when autodoc_traits is registered as a sphinx extension? HOT 1
- Document that sphinx.ext.autodoc lacks MyST support, so autodoc_traits doesn't have it either
- Setup tests HOT 3
- The `inherited-members` Sphinx directive option is respected backwards HOT 1
- Unused import is obsoleted HOT 1
- `autoclass` is not the same as `autoconfigurable` - but should be? HOT 1
- autoclass finds traits, but doesn't find their docstrings HOT 2
- New pip release request HOT 2
- Help strings incorrectly considered missing for some but not all trait types HOT 2
- Release automation HOT 3
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from autodoc-traits.