You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The fact that the autoclass_content setting is global for the whole project has become a bit of an annoyance.
I have happily set it to "both" for all my projects, but now and then I really want the option to turn it off for some classes.
The concrete example I have in front of me right now is one where I subclass NamedTupleand write an alternate constructor:
class DatasetConfiguration(NamedTuple):
"""
Configuration relevant to this dataset.
"""
internal_mount: Path
external_mount: Path
dataexport_directory: Path
dataexport_script: Path
dataexport_log: Path
@classmethod
def from_config(cls, section):
"""
Constructor.
"""
kwargs = {key: Path(value) for key, value in section.items()}
return cls(**kwargs)
I like the idea of using named tuples, because this is not dynamic data, but because I needed the second constructor (as well as some additional methods that are irrelevant here), I had to go the subclass route.
Of course, the second constructor is the only one that should be used in the scope of this code, so it's the only one that should get documented. But, since my autoclass_content is set to "both", Sphinx always pulls in the default NamedTuple.__init__ docstring...
Describe the solution you'd like
I feel that leaving autoclass_content as a global directive with no way to give exceptions, is an approach that lacks flexibility, leading to situations such as this.
I feel that the most sensible solution, in line with existing code, would be to have a :content: option for autoclass directives, with the global autoclass_content being a default for this value (and possibly simply incorporated into autodoc_default_options).
For example:
autodoc_default_options = {
"content": "both",
}
.. autoclass:: DatasetConfiguration
:content: class
(If this sounds interesting but none of the core developpers has the time to work on it, I could try my hand at it, I'd just need some pointers on where to start.)
The text was updated successfully, but these errors were encountered:
+1: Reasonable. I prefer your idea. But I feel :content: does not describe its behavior or feature. So we have to discuss a good naming for the option.
The fact that the
autoclass_content
setting is global for the whole project has become a bit of an annoyance.I have happily set it to
"both"
for all my projects, but now and then I really want the option to turn it off for some classes.The concrete example I have in front of me right now is one where I subclass
NamedTuple
and write an alternate constructor:I like the idea of using named tuples, because this is not dynamic data, but because I needed the second constructor (as well as some additional methods that are irrelevant here), I had to go the subclass route.
Of course, the second constructor is the only one that should be used in the scope of this code, so it's the only one that should get documented. But, since my
autoclass_content
is set to"both"
, Sphinx always pulls in the defaultNamedTuple.__init__
docstring...Describe the solution you'd like
I feel that leaving
autoclass_content
as a global directive with no way to give exceptions, is an approach that lacks flexibility, leading to situations such as this.I feel that the most sensible solution, in line with existing code, would be to have a
:content:
option forautoclass
directives, with the globalautoclass_content
being a default for this value (and possibly simply incorporated intoautodoc_default_options
).For example:
(If this sounds interesting but none of the core developpers has the time to work on it, I could try my hand at it, I'd just need some pointers on where to start.)
The text was updated successfully, but these errors were encountered: