Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feature request: Support numpy docstring convention #27

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

A-CGray
Copy link

@A-CGray A-CGray commented Feb 16, 2024

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

So clearly my subsection regex is incorrect.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant