Fri, Apr 24, 2020 at 02:33:30PM CEST, jtluka(a)redhat.com wrote:
>Fri, Apr 24, 2020 at 12:53:18PM CEST, olichtne(a)redhat.com wrote:
>>On Thu, Apr 23, 2020 at 04:27:21PM +0200, Jan Tluka wrote:
>>> Signed-off-by: Jan Tluka <jtluka(a)redhat.com>
>>> ---
>>> .../ENRT/ConfigMixins/BaseSubConfigMixin.py | 42 +++++++++++++++++++
>>> 1 file changed, 42 insertions(+)
>>>
>>> diff --git a/lnst/Recipes/ENRT/ConfigMixins/BaseSubConfigMixin.py
b/lnst/Recipes/ENRT/ConfigMixins/BaseSubConfigMixin.py
>>> index 6974d16f..41082783 100644
>>> --- a/lnst/Recipes/ENRT/ConfigMixins/BaseSubConfigMixin.py
>>> +++ b/lnst/Recipes/ENRT/ConfigMixins/BaseSubConfigMixin.py
>>> @@ -1,12 +1,54 @@
>>> class BaseSubConfigMixin(object):
>>> + """
>>> + This is a base class that defines common API for specific *sub*
>>> + configuration mixin classes.
>>> + """
>>> +
>>> def generate_sub_configurations(self, config):
>>> + """
>>> + A child class should override this method to extend the
*test_wide*
>>> + config with any data specific to the sub configuration, for example
NIC
>>> + offload settings. The child class must use a copy of the *config*.
>>> +
>>> + The data in the config is later used in
:meth:`apply_sub_configuration`.
>>> +
>>> + The child class must include a :py:func:`super` call of this method
so
>>> + that all other mixin classes do their part of cooperative
inheritance.
>>> + """
>>> yield config
>>>
>>> def apply_sub_configuration(self, config):
>>> + """
>>> + A child class should override this method to perform the *sub*
>>> + configuration, for example configure NIC offloads. Any data
required to
>>> + do the configuration should be added to *config* through the
>>> + :meth:`generate_sub_configurations`.
>>> +
>>> + The child class must include a :py:func:`super` call of this method
so
>>> + that all other mixin classes do their part of cooperative
inheritance.
>>> + """
>>> pass
>>>
>>> def generate_sub_configuration_description(self, config):
>>> + """
>>> + A child class should override this method to append a mixin
specific
>>> + *sub* configuration description that would show up in the recipe
log.
>>> +
>>> + The child class must include a :py:func:`super` call of this method
so
>>> + that all other mixin classes do their part of cooperative
inheritance.
>>> + """
>>> return ["Sub configuration description:"]
>>>
>>> def remove_sub_configuration(self, config):
>>> + """
>>> + A child class should override this method to perform a cleanup of
the
>>> + specific sub configuration, for example restore NIC offloads.
>>> +
>>> + Any data required to cleanup the configuration should be added to
*config*
>>> + through the :meth:`generate_sub_configurations`.
>>> +
>>> + The child class must include a :py:func:`super` call of this
>>> + method so that all other mixin classes do their part of
cooperative
>>> + inheritance.
>>> + """
>>> return
>>> --
>>> 2.21.1
>>> _______________________________________________
>>> LNST-developers mailing list -- lnst-developers(a)lists.fedorahosted.org
>>> To unsubscribe send an email to
lnst-developers-leave(a)lists.fedorahosted.org
>>> Fedora Code of Conduct:
https://docs.fedoraproject.org/en-US/project/code-of-conduct/
>>> List Guidelines:
https://fedoraproject.org/wiki/Mailing_list_guidelines
>>> List Archives:
https://lists.fedorahosted.org/archives/list/lnst-developers@lists.fedora...
>>
>>
>>This is good, but these docstrings are now inherited into the subclasses
>>so the documentation for each SubConfigMixin class now contains the same
>>text...
>>
>>-Ondrej
>
>Good catch. I did not realize that.
>
>That's a pitty. It seems that you have to either override the docstring in
>the child class or specifically list what we want to document in the :members:
>
>Or any other idea?
>
>-Jan
Hmm, that's weird. The documentation says that:
"For classes and exceptions, members inherited from base classes will be left
out when documenting all members, unless you give the inherited-members
option, in addition to members:
....
New in version 0.3.
Changed in version 3.0: It takes an anchestor class name as an
argument."
Anyway, I tried a different config option:
autodoc_inherit_docstrings = False
"This value controls the docstrings inheritance. If set to True the docstring
for classes or methods, if not explicitly set, is inherited form parents."
And that works nicely. Could you check with this setting in conf.py?
-Jan
Yes, that looks much better, it also made me notice that we should add
subconfig property docstrings to the SimpleNetworkRecipe class similar
to what you've done with the VlansRecipe.
-Ondrej