4

I can't seem to find any way to get sphinx to include doc strings from super methods. For example:

class Base(object):
    def a_method(self, param_a, param_b, **kwargs):
        """ This is an adapter method which must be implemented by each Sub class.

        :param param_a: Param A Available to all adapters.
        :type param_a: str
        :param param_b: Param B Available to all adapters.
        :type param_b: str
        """
        raise NotImplementedError('This method must be implemented in each Sub')


class Sub (Base):
    def a_method(self, param_a, param_b, param_c, **kwargs):
        """ Adapted for interface with this unique API.

        :param param_c: An option unique to this API.
        :type param_c: str
        """
        ... obtain data from API here ...
        return result
    # UPDATE TO ORIGINAL: this will combine the docs
    method_a.__doc__ += Base.method_a.__doc__
    # Now i need to combine params so that Sub supersedes Super and
    # incorporate this into sphinx.

I would like the documentation for Sub to include param_a from Base, param_b from Base, and param_c from Sub in the docs for Sub.a_method. Any way to get the output to look like this?

class Sub()
----a_method(param_a, param_b, param_c, **kwargs)
--------Super A method docs
--------Sub A method docs
--------Parameters:
-----------Param_a (str) – Param A.
-----------Param_b (str) – Param B.
-----------Param_c (str) – Param C.

Arctelix
  • 4,478
  • 3
  • 27
  • 38
  • You could put an explicit link to it in the subclass implementation docstring. – jonrsharpe Feb 16 '15 at 19:49
  • yes, that's what i'm doing now and gets the job done. It would be better to actually have the docs right there. Instead of a link i'm looking for an import... – Arctelix Feb 16 '15 at 20:23
  • 1
    would this work : http://stackoverflow.com/a/2025599/671543 ? (or does it only work for classes?) – njzk2 Feb 16 '15 at 20:27
  • @njk2 Gave it a shot and the docstring for ``Sub.a_method`` is unaffected – Arctelix Feb 16 '15 at 20:41
  • @njk2 Actually it does work! Not ideal, but it does combine the doc strings. Still i wonder if this is possible via some existing sphinx directive that i have overlooked, – Arctelix Feb 16 '15 at 20:45
  • It's not a directive, but autodoc's [docstring-preprocessing](http://sphinx-doc.org/ext/autodoc.html#docstring-preprocessing) feature might be helpful. It lets you modify the docstring in place as the docs are generated. – morric Feb 18 '15 at 09:22
  • Thanks @morric , this is interesting. Now i just need to find a way to incorporate ``method_a.__doc__ += Base.method_a.__doc__``. I need one list of params combined where Sub.method_a params supersede Super.method_a params.. Almost there – arctelix 22 mins ago – Arctelix Feb 18 '15 at 17:54
  • Actually, keeping the combine statement in the class could be a good thing. This way the docs are combined in python doc access as well as sphinx. – Arctelix Feb 18 '15 at 17:57
  • Not sure how relevant this is, but OP, your code shows poor design. It violates the [Liskov substitution principle](http://en.wikipedia.org/wiki/Liskov_substitution_principle), since it is legal to call `base_instance.a_method(x, y)`, but illegal to make the same call on an instance of `Sub`. That might be why Sphinx doesn't let you supersede params like that. – Kevin Feb 18 '15 at 19:09
  • @ kevin, Are you referring to addition of param_c to the base method? If so i would agree (bad example code). However, your quote "illegal to make the same call on an instance of Sub" is a pattern that i see all the time.... As long as the inheritance chain is: shape -> four_sided_shape -> rectangle OR shape -> four_sided_shape -> square AND NOT shape -> four_sided_shape -> triangle. – Arctelix Feb 18 '15 at 21:10

0 Answers0