On Fri, Apr 24, 2020 at 02:53:29PM +0200, Jan Tluka wrote:
> 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