Open lukashergt opened 5 years ago
Hi Lukas! Thanks for your report :) Yes, this might cause a problem since the Parameters are in the
param_like_sections
attribute. Could you give a small example? I suspect you could simply change this behaviour by subclassing the DocstringProcessor
and putting the 'Parameters'
in the text_sections
attribute:
class DocstringProcessorWithBlanks(DocstringProcessor):
param_like_sections = [s for s in DocstringProcessor.param_like_sections
if s != 'Parameters']
text_sections = ['Parameters'] + DocstringProcessor.text_sections
Or simply put all param_like_sections
into the text_sections
:
class DocstringProcessorWithBlanks(DocstringProcessor):
param_like_sections = []
text_sections = DocstringProcessor.text_sections + \
DocstringProcessor.param_like_sections
Thanks for the quick reply, Philipp!
Haha, sorry should have directly tried to strip it down, then my question would have been more specific...
So, as it turns out for simple functions blank lines are fine. However, in class methods blank lines don't work.
import docrep
docstrings = docrep.DocstringProcessor()
@docstrings.get_sectionsf('do_something')
@docstrings.dedent
def do_something(a, b):
"""
Add two numbers
Parameters
----------
a: int
The first number
b: int
The second number
Returns
-------
int
`a` + `b`"""
return a + b
@docstrings.dedent
def do_more(c, *args, **kwargs):
"""
Add two numbers and multiply it by c
Parameters
----------
c: int
multiplication parameter
%(do_something.parameters)s
Returns
-------
int
(`a` + `b`) * c"""
return do_something(*args, **kwargs) * c
print(do_more.__doc__)
Add two numbers and multiply it by c
Parameters
----------
c: int
multiplication parameter
a: int
The first number
b: int
The second number
Returns
-------
int
(`a` + `b`) * c
import docrep
docstrings = docrep.DocstringProcessor()
class A:
@docstrings.get_sectionsf('do_something')
@docstrings.dedent
def do_something(a, b):
"""
Add two numbers
Parameters
----------
a: int
The first number
b: int
The second number
Returns
-------
int
`a` + `b`"""
return a + b
@docstrings.dedent
def do_more(c, *args, **kwargs):
"""
Add two numbers and multiply it by c
Parameters
----------
c: int
multiplication parameter
%(do_something.parameters)s
Returns
-------
int
(`a` + `b`) * c"""
return do_something(*args, **kwargs) * c
a = A
print(a.do_more.__doc__)
b
missing in printed docstringAdd two numbers and multiply it by c
Parameters
----------
c: int
multiplication parameter
a: int
The first number
Returns
-------
int
(`a` + `b`) * c
Both of your suggestions seem to work. Thanks, Philipp, that way I can keep my blank lines.
Both of your suggestions seem to work.
Great 😄
So, as it turns out for simple functions blank lines are fine. However, in class methods blank lines don't work.
This is weird because actually the DocstringProcessor
does not care whether it is a method or a function. I'll have a look into it and until then, we should keep this issue open.
As a little comment: the sections in the text_sections
attribute assume that they end either by the next section or the end of the docstring. Therefore something like
def func(a=1):
"""
An awesome function
Parameters
----------
a: int
A parameter
And here we have a paragraph that has nothing to
do with the Parameters section
"""
will cause problems if you have the 'Parameters'
in the text_sections
attribute.
sections in the
text_sections
attribute assume that they end either by the next section or the end of the docstring
Good to know, I'll look out for that, but I guess typically this won't be an issue as the parameters section usually is followed by the results section.
FYI: I am currently using this 'bug' as a feature. If I want to stop certain parameters from being inherited by subclasses I but them after a line break. This way I can re-define those specific parameters in subclasses without having duplicates (or without having the deal with removing them from the docrep dict).
This pertains to the feature request I just posted (issue #16)
Does
docrep
require the parameters in the docstring to be written without a blank line separating them? It seems like a blank line is taken as the end of the parameter section.Would it be possible to allow blank lines such that the raw docs look a little neater?