[Solved] How do I disable "missing docstring" warnings at a file-level in Pylint? – Pylint

The Problem:

How do I disable the "missing docstring" warnings at a file-level in Pylint but still keep the docstring checks for classes, methods and functions?

The Solutions:

Solution 1: Disabling “missing docstring” warnings at a file-level in Pylint

In Pylint, the “missing docstring” error can be disabled at a file-level. To achieve this, utilize the following steps:

1. Utilize Sub-Messages: For Pylint versions 2.4 and above, three sub-messages are available:
   • C0114: missing-module-docstring
   • C0115: missing-class-docstring
   • C0116: missing-function-docstring

   Disable only the C0114 sub-message in the .pylintrc file to disable “missing docstring” warnings for files. This allows other docstring warnings to remain active.

2. Disable All Docstring Warnings: For Pylint versions prior to 2.4, there is no specific sub-message for missing module docstrings. Thus, to disable all docstring warnings, disable the C0111 message. However, this will disable all docstring warnings, including those for functions, classes, and methods.
3. Add a Minimal Docstring: Alternatively, you can add a minimal docstring to the top of the file, containing a brief description of its purpose. While not ideal for thorough documentation, it can suppress the missing docstring warning.

Solution 2: Using ‘–disable’ parameter

A more precise approach is to disable specific rules rather than using ‘–errors-only’. This can be achieved with the ‘–disable=<msg ids>, -d <msg ids>’ parameter.

To find the message IDs, refer to the [list provided here][2]. For the error mentioned in the question, the message ID is ‘C0111’.

The method of using ‘–disable=’ varies depending on your chosen IDE or Text Editor. For instance, in VS Code, you can add the following line to your ‘settings.json’ file:

"python.linting.pylintArgs": ["--disable=C0111"]

Solution 3: Disable docstring warnings using comment directives

To disable “missing docstring” warnings at a file level, add the following comment directives at the beginning of the file:

# pylint: disable=missing-module-docstring
# pylint: disable=missing-class-docstring
# pylint: disable=missing-function-docstring

These directives will prevent Pylint from issuing warnings about missing docstrings in the file.

Solution 4: Disable "missing docstring" warnings with ‘python.linting.pylintArgs’ in VSCode

To disable “missing docstring” warnings at a file-level in PyLint using VSCode’s global settings:

1. Open the VSCode settings (File > Preferences > Settings).
2. Search for "python.linting.pylintArgs".
3. Add the following arguments to the "python.linting.pylintArgs" array:

--disable=missing-class-docstring
--disable=missing-function-docstring

5. Save the settings.

This will disable the "missing docstring" warnings for classes and functions in PyLint, while still allowing you to receive warnings for missing docstrings within classes, functions, and methods.

You can find a full reference to Pylint options and switches here.

Solution 5: Using grep and sed for selective disabling of missing docstring warnings

To selectively disable missing docstring warnings at a file level in Pylint, you can use the following steps:

1. Create a custom message template using the --msg-template flag:

   pylint */*.py --msg-template='{path}: {C}:{line:3d},{column:2d}: {msg}' | grep docstring | grep -v module
   

This command will generate a list of all missing docstring warnings, excluding those related to modules.

2. Use the grep and sed commands to modify the generated list and remove any warnings that you want to disable:

   grep -v 'path/to/file1.py' list_of_warnings.txt > modified_list.txt
   sed -i 's/path\/to\/file2.py:/path\/to\/file2.py: --disable=missing-docstring:/' modified_list.txt
   

This will remove the warnings for specific files (e.g., path/to/file1.py and path/to/file2.py) and append --disable=missing-docstring to the warnings for other files.

3. Finally, run Pylint again with the modified list of warnings:

   pylint */*.py < modified_list.txt
   

This will run Pylint with the missing docstring warnings disabled for the specified files while still reporting other types of warnings.