Chilipp
commented
3 years ago hey @mario-bermonti!
two things here:
@docstrings.dedent(4)is wrong. you can either calldedentwith a string (e.g.dedent('something')or use it as a decorator without a function call, i.e.@docstrings.dedent def myfunc():...- what is causing your issue is yes, the order of the methods is indeed important. In your second call, when you do a
@docstrings.dedent(4) def _check_silent_letters(self):the docstring of
_check_silent_uhas not yet been processed. So it cannot modify the docstring. This is not something specific todocrep, this is specific to howpythoninterpretes your code.
If you really do not want to change the order, you could move the docstrings.dedent call to the end, i.e. something like
from docrep import DocstringProcessor
DocstringProcessor.text_sections = ["Rules", "Notes", "Warnings"]
docstrings = DocstringProcessor()
class W():
def _check_silent_letters(self):
"""
Count the number of silent letters.
Silent letters are graphemes that do not have a phonemic representation.
In Spanish, silent letters are *h*s and *u*s that meet certain criteria.
%(silent_u.parameters)s
Rules
-----
%(silent_u.rules)s
Returns
-------
silent_letter_count : int
Number of silent letters.
"""
pass
@docstrings.get_sections(base="silent_u", sections=["Parameters", "Rules"])
@docstrings.dedent
def _check_silent_u(self):
"""
Count the number of silent letters *u*.
Parameters
----------
x : int
some param
Rules
-----
*u*: when preceded by a *g* or *q* and
followed by an *i* or *e*. These follow the pattern *gui*, *gue*,
*que*, *qui*.
Returns
-------
silent_u_count: int
Number of silent letters *u* in the word
"""
pass
docstrings.dedent(_check_silent_letters)
print(W._check_silent_letters.__doc__)
mario-bermonti
When using docrep to reuse an instance method's docstring, I found that the order of the methods matter. The method from which the docstring is extracted has to be defined before the method that uses its docstring.
I guess it makes sense, but it took me by surprise because when dealing with classes I usually don't think of methods in a linear way (as in procedural programming). I usually think of each method in the API as independent from each other in terms of the user calling it.
Is this intended or just something for which there is no workaround? I would prefer not to move the methods around in the class, but it wouldn't be the end of the world. I usually write the more general method that uses other private methods and just after it I add the methods that are used by the first method.
If it is intended or unavoidable then it should probably be documented.
Some code to illustrate this:
This will work:
But this will not work: