`:members:` and `:inherited-members:` implied for traits - a bit unexpected -> discussion of options for `autoconfigurable` about autodoc-traits HOT 5 OPEN

@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:

1. what does it look like to request all config on the current class, but not inherited config?
2. what does it look like to request all config inherited by the current class (the default behavior before #28)?
3. what does it look like to include only specific (or all minus specific) config members, a la the existing :members: or :exclude-members:?
4. what does autoconfigurable: Class with no options given do by default (presumably it should be different from autoclass: 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.

2. 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.

1. 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.

3. 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.

4. what does autoconfigurable: Class with no options given do by default (presumably it should be different from autoclass: 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.