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