Tools should not be named after style guide PEPs. A style guide is a document written for humans, and has lots of subtlety. Issues caused by the rigidity or simplicity of the tool end up causing pointless discussion about the letter of the PEP, as if it was a law, which was never the intention of the PEP. If you want to write a tool that checks style, please give it some clever name, don't name it after a PEP, so it's clear that whenever humans don't like what the tool says, it is a tool issue, not an issue with the PEP (which is merely intended to guide humans, not to require them to follow it every time).

There are lots of projects out there using the google docstring convention. Given numpy has been recently added under #129, this is a request to add the google docstring convention.

Comparison between the two can be found here.

Many other python formatting/style tools have added support for the pyproject.toml file's [tool.*] sections for their configuration. Is this something that pydocstyle would be open to supporting?

Following the existing conversation seen here (https://github.com/PyCQA/pydocstyle/issues/443)

This issue is to request that hanging indentation documentation be added to Google style.

Args

Currently this style is recommended by pydocstyle:

    Args:
        verbose (bool): If True, print out as much information as possible.
            If False, print out concise "one-liner" information.

And this issue is to request that this other style also be valid:

    Args:
        verbose (bool): 
            If True, print out as much information as possible.
            If False, print out concise "one-liner" information.

@samj1912's link to Google-style, http://google.github.io/styleguide/pyguide.html#383-functions-and-methods, shows that this is already allowed in Google style.

Returns / Yields

The Google style guide explicitly mentions newlines being allowed for args. I'd like to further propose that the same apply for Return docstrings.

For example, this

    Returns
        :obj:`list` of :obj:`tuple` str or :class:`my_package.modules.MyKlass`: Line already exceeds 0 characters.

Can become this

    Returns
        :obj:`list` of :obj:`tuple` str or :class:`my_package.modules.MyKlass`: 
            Each line is within 80 characters.

To the maintainers of this repo - would you accept a PR to add this feature?

Sources for docstring convention:

Google Style Guide and Napoleon Google Style Guide

Rationale for exclusions of errors:

• D203: Multiple examples with class docstrings without blank line.
• D204: Same as above.
• D213: All multiline summaries start immediately after the triple quotes.
• D215: N/A no underlines.
• D400: First line can end with "period, question mark, or exclamation point".
• D401: Style guide explicitly says not to use imperative mood and use descriptive mood.
• D404: Clearly allowed WRT to the above. There is also an example using "This".
• D406: Section names end with a colon.
• D407: N/A no underlines.
• D408: N/A no underlines.
• D409: N/A no underlines.

Adds the following violations:

• D415: First line of docstring should end with a period, question mark, or exclamation point
• D416: Section name should end with a semicolon
• D417: Missing arguments in the function docstring

Thanks for submitting a PR!

Please make sure to check for the following items:

• [x] Add unit tests and integration tests where applicable.
  If you've added an error code or changed an error code behavior, you should probably add or change a test case file under tests/test_cases/ and add it to the list under tests/test_definitions.py.
  If you've added or changed a command line option, you should probably add or change a test in tests/test_integration.py.
• [ ] Add a line to the release notes (docs/release_notes.rst) under "Current Development Version".
  Make sure to include the PR number after you open and get one.

Please don't get discouraged as it may take a while to get a review.

I have the following docstring.

    @property
    def file_path(self):
        '''Alias for consistency with the rest of pocketlint.'''

The error is

     142: D401: First line should be imperative: 'Alia', not 'Alias'

While the intent is noble, I think that the current implementation is not helpful.

Is there anyone using this check in production code?

If a check could not be done, I prefer to not try to automate it as it is not fun to maintain a list of ignored values..

Thanks!

This permit to release on pypi if a value for PYPI_API_TOKEN is set in github settings. The release is done when a release is created/published in github interface.

Relates to #575

This is to match Guido's change here: https://hg.python.org/peps/rev/9b715d8246db and the reason is in a comment by Guido here (first comment at bottom):

http://raspberry-python.blogspot.com/2015/01/significant-pep257-change.html

The test requirements are from my own virtual environment where tests execute correctly. I can bump them later.

While I could push this commit directly to Travis CI, I think the Travis CI hook needs to be activated before we merge this commit. @halst I don't have the admin privileges to activate the service hook. Could you do that?

This fixes #48.

This PR closes #447.

Changes

• Fix a small unrelated bug, where inline comments in .ini files behaved differently when autodetected by _get_config_file_in_folder and when manually specified by --config.

• Add toml as a package dependency (setup.py) and as a pinned runtime dependency (requirements/runtime.txt).

• Implement TomlParser - a thin wrapper around the toml library with minimal API parity with RawConfigParser.

• Autodetect pyproject.toml configuration

• Autodetect tool.pydocstyle section

• Implement error code list support for toml. This is so that you can use

  select = [
      "D100",
      # This line is ignored
      "D103",
  ]
  

  and not only

  select = "D100,D103"
  

• Almost all tests in test_integration.py which used the env fixture now are run for both toml and ini versions of the configuration (47 tests).

• 2 tests are only run for ini configuration: test_ignores_whitespace_in_fixed_option_set and test_multiple_lined_config_file. In toml, strings must be quoted, so comments and newlines inside the strings don't make much sense, which is what these tests are checking. Instead, I've implemented 2 "equivalent" toml tests that also check the list support: test_accepts_ignore_error_code_list and test_accepts_select_error_code_list.

Please make sure to check for the following items:

• [x] Add unit tests and integration tests where applicable.
• [ ] Add a line to the release notes (docs/release_notes.rst) under "Current Development Version".
  Make sure to include the PR number after you open and get one.

There's currently no "Current Development Version" section in docs/release_notes.rst. Where should I add the changes?

In order to determine the missing arguments, we currently use ast.parse to parse partial source code. This parsing might lead to syntax errors. We catch the syntax error and make the parsing more resilient to errors in the source code.

Fixes #437

Thanks for submitting a PR!

Please make sure to check for the following items:

• [x] Add unit tests and integration tests where applicable.
  If you've added an error code or changed an error code behavior, you should probably add or change a test case file under tests/test_cases/ and add it to the list under tests/test_definitions.py.
  If you've added or changed a command line option, you should probably add or change a test in tests/test_integration.py.
• [ ] Add a line to the release notes (docs/release_notes.rst) under "Current Development Version".
  Make sure to include the PR number after you open and get one.

Please don't get discouraged as it may take a while to get a review.

pydocstyle started reporting false positives of D417 in google convention on version 6.2.0 and later. Version 6.1.1 does not suffer the same problem. Consider following code:

def sum(a: int, b: int, c: int):
    """Sum three numbers.

    Args:
        a: First number.
        b: Second number.
        c: Third number.

    Some further details.
    """
    return a + b + c

When I run pydocstyle example.py --select=D417, I get the following output:

example.py:2 in public function `sum`:
        D417: Missing argument descriptions in the docstring (argument(s) b, c are missing descriptions in 'sum' docstring)

I'd expect no errors since all the arguments are properly listed in docstring.

You can't overload an init without failing one or the other of these rules currently:

class A:
    @overload
    def __init__(self):
                           # This fails D107: Missing docstring in __init__
        pass

    def __init__(self):
        """Docstring."""
        pass

class B:
    @overload
    def __init__(self):
        """Docstring."""  # This fails D418: Function/ Method decorated with @overload shouldn't contain a docstring
        pass

    def __init__(self):
        """Docstring."""
        pass

This is the only way pydocstyle will obey its own match rules.

Thanks for submitting a PR!

Please make sure to check for the following items:

• [x] Add unit tests and integration tests where applicable.
  If you've added an error code or changed an error code behavior, you should probably add or change a test case file under tests/test_cases/ and add it to the list under tests/test_definitions.py.
  If you've added or changed a command line option, you should probably add or change a test in tests/test_integration.py.
• [x] Add a line to the release notes (docs/release_notes.rst) under "Current Development Version".
  Make sure to include the PR number after you open and get one.

Please don't get discouraged as it may take a while to get a review.

pycodestyle relies on function doctrings to show the linting errors. When you run a program with PYTHONOPTIMIZE=2 environment variable or the -OO option the docstrings are stripped, so the next error is raised:

... (traceback)

  File "/.../site-packages/pydocstyle/checker.py", line 160, in check_source
    partition = this_check.__doc__.partition('.\n')
AttributeError: 'NoneType' object has no attribute 'partition'

#534 enabled usage of pydocstyle with pyproject.toml for configuration. In that PR, it was discussed that toml shouldn't be a hard dependency for using pydocstyle (which I agree with), and that it should simply throw a warning if a pyproject.toml file is detected without the toml package present to read it. However, this is problematic when using pydocstyle as a pre-commit hook because pre-commit will silently consume stdout unless the hook returns a nonzero exit code.

I see a few potential solutions here, which I've placed in order of preference:

1. Use the additional_dependencies feature of pre-commit to always require toml when installing the pydocstyle pre-commit hook. I see the argument for not wanting to error without toml in a general setting, but in the context of pre-commit where the dependencies can be tightly managed I think it's OK to have this dependency encoded.
2. Change the warning to an error, but also add a grep (or equivalent) of a pyproject.toml file (if one exists) to see whether the string [tool.pydocstyle] is present in the file as a precondition of erroring. This is a bit more engineering effort, but if avoiding requiring toml is important enough even in a pre-commit hook then this would be a way to do a more cursory check of the file without parsing it.
3. Set verbose: True in the pre-commit hook definition. This choice has the downside of always making pydocstyle noisier, but it at least ensures that the warning will be visible.
4. The status quo. This solution puts the onus on the user to realize that pydocstyle fails silently in this case. I personally don't think this is a viable solution, but I listed it in case the project maintainers feel otherwise.

I am happy to make a PR if we could come to a consensus on the preferred solution.