There are many configuration options available. They can be used invidually or together.
For how to actually implement these options in your commands, please read this page: How to configure pydoclint.
Table of Contents
--quiet (shortform: -q)--exclude--style--arg-type-hints-in-docstring and --arg-type-hints-in-signature--check-arg-order (shortform: -ao, default: True)--skip-checking-short-docstrings (shortform: -scsd, default: True)--skip-checking-raises (shortform: -scr, default: False)--allow-init-docstring (shortform: -aid, default: False)--require-return-section-when-returning-nothing (shortform: -rrs, default: False)--check-return-types (shortform: -crt, default: True)--require-yield-section-when-yielding-nothing (shortform: -rys, default: True)--check-yield-types (shortform: -cyt, default: True)--ignore-underscore-args (shortform: -iua, default: True)--ignore-private-args (shortform: -ipa, default: False)--check-class-attributes (shortform: -cca, default: True)--should-document-private-class-attributes (shortform: -sdpca, default: False)--treat-property-methods-as-class-attributes (shortform: -tpmaca, default: False)--only-attrs-with-ClassVar-are-treated-as-class-attrs (shortform: -oawcv, default: False)--should-document-star-arguments (shortform: -sdsa, default: True)--check-style-mismatch (shortform: -csm, default: False)--check-arg-defaults (shortform: -cad, default: False)--baseline--generate-baseline (default: False)--auto-regenerate-baseline (shortform: -arb, default: True)--show-filenames-in-every-violation-message (shortform: -sfn, default: False)--native-mode-noqa-location (shortform: -nmnl, default: docstring)--config (default: pyproject.toml)--quiet (shortform: -q)This flag activates the “quite mode”, in which no output will be printed to the command line if there are no violations.
By default, this flag is not activated, so the files that are scanned are printed in the command line.
pydoclint --quiet <FILE_OR_FOLDER>
This option is only available in the “native” command-line mode, rather than in flake8. If you use pydoclint in flake8, please use flake8’s own verbosity configuration instead.
--excludeYou can use this option to exclude files within the given folder. It is a regex pattern of full file paths.
For example:
pydoclint --exclude='\.git|\.tox|tests/data' <FOLDER_NAME>
This option is only available in the native command-line mode. If you use
pydoclint within flake8, you can use flake8’s
--exclude option.
--styleWhich style of docstring is your code base using. Right now there are three
available choices: numpy, google, and sphinx. The default value is
numpy.
pydoclint --style=google <FILE_OR_FOLDER>
or
flake8 --style=google <FILE_OR_FOLDER>
--arg-type-hints-in-docstring and --arg-type-hints-in-signature--arg-type-hints-in-docstring
-athdTrueTrue, there need to be type hints in the argument list of a
docstringFalse, there cannot be any type hints in the argument list of a
docstring--arg-type-hints-in-signature
-athsTrueTrue, there need to be type hints for input arguments in the
function/method signatureFalse, there cannot be any type hints for input arguments in the
function/method signatureNote: if users choose True for both options, the argument type hints in the
signature and in the docstring need to match, otherwise there will be a style
violation.
--check-arg-order (shortform: -ao, default: True)If True, the input argument order in the docstring needs to match that in the
function signature.
To turn this option on/off, do this:
pydoclint --check-arg-order=False <FILE_OR_FOLDER>
or
flake8 --check-arg-order=False <FILE_OR_FOLDER>
--skip-checking-short-docstrings (shortform: -scsd, default: True)If True, pydoclint won’t check functions that have only a short description
in their docstring.
To turn this option on/off, do this:
pydoclint --skip-checking-short-docstrings=False <FILE_OR_FOLDER>
or
flake8 --skip-checking-short-docstrings=False <FILE_OR_FOLDER>
--skip-checking-raises (shortform: -scr, default: False)If True, pydoclint won’t report DOC501 or DOC502 if there are raise
statements in the function/method but there aren’t any “raises” sections in the
docstring (or vice versa).
--allow-init-docstring (shortform: -aid, default: False)If it is set to True, having a docstring for class constructors
(__init__()) is allowed, and the arguments are expected to be documented
under __init__() rather than in the class docstring.
Note: the default is set to False because not every class has an __init__
method (such as classes that inherit from parent classes), but every class must
have the class ClassName declaration.
--require-return-section-when-returning-nothing (shortform: -rrs, default: False)If False, a “return” section is not necessary in the docstring if the
function implicitly returns None (for example, doesn’t have a return
statement, or has -> None as the return annotation) or doesn’t return at all
(has return type NoReturn).
--check-return-types (shortform: -crt, default: True)If True, check that the type(s) in the docstring return section and the return annotation in the function signature are consistent
--require-yield-section-when-yielding-nothing (shortform: -rys, default: True)If False, a yields section is not needed in docstring if the function yields None.
--check-yield-types (shortform: -cyt, default: True)If True, check that the type(s) in the docstring “yields” section and the return annotation in the function signature are consistent.
--ignore-underscore-args (shortform: -iua, default: True)If True, underscore arguments (such as _, __, …) in the function signature do not need to appear in the docstring.
Note: “underscore arguments” are not the same as “private arguments” (i.e.,
“arguments with leading underscores”) such as _a.
--ignore-private-args (shortform: -ipa, default: False)If True, private arguments (those with leading underscores in their names but
are not purely _, __, etc.) in the function signature do not need to appear
in the docstring.
--check-class-attributes (shortform: -cca, default: True)If True, check the class attributes (defined under the class definition) against the “Attributes” section of the class’s docstring.
Please read this page for more instructions.
--should-document-private-class-attributes (shortform: -sdpca, default: False)If True, private class attributes (those that start with leading _) should be
documented. If False, they should not be documented.
--treat-property-methods-as-class-attributes (shortform: -tpmaca, default: False)If True, treat @property methods as class properties. This means that they
need to be documented in the “Attributes” section of the class docstring, and
there cannot be any docstring under the @property methods. This option is only
effective when –check-class-attributes is True.
--only-attrs-with-ClassVar-are-treated-as-class-attrs (shortform: -oawcv, default: False)If True, only the attributes whose type annotations are wrapped within
ClassVar (where ClassVar is imported from typing) are treated as class
attributes, and all other attributes are treated as instance attributes.
--should-document-star-arguments (shortform: -sdsa, default: True)If True, “star arguments” (such as *args, **kwargs, **props, etc.) in the
function signature should be documented in the docstring. If False, they should
not appear in the docstring.
--check-style-mismatch (shortform: -csm, default: False)If True, check that style specified in –style matches the detected style of
the docstring. If there is a mismatch, DOC003 will be reported. Setting this
to False will silence all DOC003 violations.
Read more about this config option and DOC003 at
https://jsh9.github.io/pydoclint/style_mismatch.html.
--check-arg-defaults (shortform: -cad, default: False)If True, docstring type hints should contain default values consistent with the function signature. If False, docstring type hints should not contain default values. (Only applies to numpy style for now.)
--baselineBaseline allows you to remember the current project state and then show only new violations, ignoring old ones. This can be very useful when you’d like to gradually adopt pydoclint in existing projects.
If you’d like to use this feature, pass in the full file path to this option.
For convenience, you can write this option in your pyproject.toml file:
[tool.pydoclint]
baseline = "pydoclint-baseline.txt"
If you also set --generate-baseline=True (or --generate-baseline True),
pydoclint will generate a file that contains all current violations of your
project.
If --generate-baseline is not passed to pydoclint (the default is False),
pydoclint will read your baseline file, and ignore all violations specified
in that file.
--generate-baseline (default: False)Required to use with --baseline option. If True, generate the baseline file
that contains all current violations.
--auto-regenerate-baseline (shortform: -arb, default: True)If it’s set to True, pydoclint will automatically regenerate the baseline file every time you fix violations in the baseline and rerun pydoclint.
This saves you from having to manually regenerate the baseline file by setting
--generate-baseline=True and run pydoclint.
--show-filenames-in-every-violation-message (shortform: -sfn, default: False)If False, in the terminal the violation messages are grouped by file names:
file_01.py
10: DOC101: ...
25: DOC105: ...
37: DOC203: ...
file_02.py
24: DOC102: ...
51: DOC107: ...
126: DOC203: ...
246: DOC105: ...
If True, the file names are printed in the front of every violation message:
file_01.py:10: DOC101: ...
file_01.py:25: DOC105: ...
file_01.py:37: DOC203: ...
file_02.py:24: DOC102: ...
file_02.py:51: DOC107: ...
file_02.py:126: DOC203: ...
file_02.py:246: DOC105: ...
This can be convenient if you would like to click on each violation message and go to the corresponding line in your IDE. (Note: not all terminal app offers this functionality.)
--native-mode-noqa-location (shortform: -nmnl, default: docstring)This option controls where pydoclint looks for inline # noqa: DOCxxx
comments when running in native mode (i.e., outside of Flake8). Two values are
accepted:
docstring (default): expects the # noqa: DOCxxx comment on the same line
as the closing triple quotes of the docstring.definition: expects the # noqa: DOCxxx comment on the line containing the
function/method/class definition.Only DOC-prefixed violation codes are honored; other codes are ignored by the
native parser. This setting has no effect in Flake8 mode, which is controlled
by Flake8’s own noqa handling.
--config (default: pyproject.toml)The full path of the .toml config file that contains the config options. Note that the command line options take precedence over the .toml file. Look at this page: How to configure pydoclint