First of all, thanks for your efforts on this package, I've been looking for a tool to do this kind of checking for quite a while. My only issue is that the numpy docstring convention (that I use) is not compatible with the way this package currently checks for sections and subsections.
As an example, here is a function in my code I tested flake8-docstrings-complete on:
def generateCantileverMesh(numBlocks):
"""Generate the mesh data for a basic cantilever truss
The cantilever is made of repeated blocks of length 0.5m in which all 4 corners are connected by trusses.
This is taken from `"A novel approach to discrete truss design problems using mixed integer neighborhood search." by Shahabsafa et al.<https://doi.org/10.1007/s00158-018-2099-8>`_
Parameters
----------
numBlocks : int
Number of blocks to generate
Returns
-------
2*(1 + numBlocks) x 2 array
Node coordinates
(5*numblocks) x 2 array
Node connectivity data
"""
nodeCoords = []
connectivity = []
L = 0.5
for ii in range(numBlocks):
if ii == 0:
nodeCoords += [[ii * L, L], [ii * L, 0.0]]
nodeCoords += [[(ii + 1) * L, L], [(ii + 1) * L, 0.0]]
connectivity += [
[2 * ii, 2 * ii + 2],
[2 * ii + 2, 2 * ii + 3],
[2 * ii + 3, 2 * ii + 1],
[2 * ii, 2 * ii + 3],
[2 * ii + 1, 2 * ii + 2],
]
return np.array(nodeCoords), np.array(connectivity)
When I run flake8 on this I get:
Examples/Cantilever/test.py:28:5: DCO020 a function/ method with arguments should have the arguments section in the docstring, more information: https://github.com/jdkandersson/flake8-docstrings-complete#fix-dco020
Examples/Cantilever/test.py:62:5: DCO030 function/ method that returns a value should have the returns section in the docstring, more information: https://github.com/jdkandersson/flake8-docstrings-complete#fix-dco030
Because flake8-docstrings-complete is expecting something like Parameters: instead of:
Parameters
----------
A similar thing happens for the subsections since the current regex is looking for numBlocks: instead of numBlocks :
I don't expect you to actually merge my very hacky implementation below, but I figured it might give you some inspiration if you did want to implement this.
To support the numpy format I edited the section name and subsection regex's (here's a test I made for the section name regex) and altered _get_sections to use 2 lines at a time when checking for section headings. With these changes I now get:
Examples/Cantilever/test.py:27:28: DCO023 "numBlocks" argument should be described in the docstring, more information: https://github.com/jdkandersson/flake8-docstrings-complete#fix-dco023
First of all, thanks for your efforts on this package, I've been looking for a tool to do this kind of checking for quite a while. My only issue is that the numpy docstring convention (that I use) is not compatible with the way this package currently checks for sections and subsections.
As an example, here is a function in my code I tested
flake8-docstrings-completeon:When I run flake8 on this I get:
Because
flake8-docstrings-completeis expecting something likeParameters:instead of:A similar thing happens for the subsections since the current regex is looking for
numBlocks:instead ofnumBlocks :I don't expect you to actually merge my very hacky implementation below, but I figured it might give you some inspiration if you did want to implement this.
To support the numpy format I edited the section name and subsection regex's (here's a test I made for the section name regex) and altered
_get_sectionsto use 2 lines at a time when checking for section headings. With these changes I now get:So clearly my subsection regex is incorrect.