Làm cách nào để tắt cảnh báo "thiếu chuỗi tài liệu" ở cấp tệp ở Pylint?

Question

Pylint ném lỗi rằng một số tệp thiếu tài liệu. Tôi cố gắng và thêm docstrings cho mỗi lớp, phương thức và chức năng nhưng có vẻ như Pylint cũng kiểm tra xem các tệp có nên là một docstring ở đầu nó hay không. Tôi có thể vô hiệu hóa điều này bằng cách nào đó không? Tôi muốn được thông báo về một docstring là thiếu bên trong một lớp, chức năng hoặc phương pháp nhưng nó không phải là bắt buộc đối với một tập tin để có một docstring.

(Có một thuật ngữ của thuật ngữ pháp lý thường được tìm thấy ở phần đầu của một tập tin mã nguồn độc quyền? Bất kỳ ví dụ? Tôi không biết cho dù đó là một okay để gửi một câu hỏi tầm thường như riêng biệt.)

Answer 1

Nó là tốt đẹp cho một mô-đun Python để có một docstring, giải thích những gì các mô-đun hiện, những gì nó cung cấp, ví dụ về cách sử dụng các lớp học. Điều này khác với các nhận xét mà bạn thường thấy ở đầu tệp cung cấp thông tin bản quyền và giấy phép, IMO không được đưa vào chuỗi tài liệu (một số thậm chí cho rằng chúng sẽ biến mất hoàn toàn, xem ví dụ: http://hackerboss.com/get-rid-of-templates/)

Pylint không có một mã riêng biệt cho các nơi khác nhau mà docstrings có thể xảy ra, vì vậy tất cả các bạn có thể làm là vô hiệu hóa C0111. Vấn đề là nếu bạn vô hiệu hóa điều này ở phạm vi mô-đun, sau đó nó sẽ bị vô hiệu hóa ở mọi nơi trong mô-đun (tức là bạn sẽ không nhận được bất kỳ dòng C nào cho chức năng thiếu/lớp/phương thức docstring. đóng góp cho pylint issue on github này nếu nó làm phiền bạn

Vì vậy, những gì tôi đề nghị được bổ sung thêm rằng docstring nhỏ mất tích, nói cái gì đó như:.

""" 
high level support for doing this and that. 
""" 

Chẳng bao lâu, bạn sẽ được tìm kiếm điều hữu ích để đưa vào đó , chẳng hạn như cung cấp các ví dụ về cách sử dụng các lớp/chức năng khác nhau của mô-đun không nhất thiết thuộc về các tài liệu riêng lẻ của các lớp/chức năng (chẳng hạn như cách tương tác hoặc một thứ gì đó giống như hướng dẫn nhanh).

Answer 2

Tôi đã tìm kiếm câu trả lời vì, như @cerin cho biết, trong các dự án Django, nó cồng kềnh và dư thừa để thêm tài liệu mô-đun vào mọi tệp mà django tự động tạo khi tạo ứng dụng mới.

Vì vậy, như một cách giải quyết cho một thực tế rằng pylint không cho phép bạn chỉ định một sự khác biệt trong docstring loại, bạn có thể làm điều này:

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

Bạn cần phải cập nhật các msg-mẫu để khi bạn grep bạn vẫn sẽ biết tên tệp. Điều này trả về tất cả các loại thiếu-docstring khác không bao gồm các mô-đun.

Sau đó, bạn có thể sửa chữa tất cả những lỗi, và sau đó chỉ cần chạy:

pylint */*.py --disable=missing-docstring 

Answer 3

Tôi nghĩ việc sửa chữa chỉ là tương đối dễ dàng mà không cần vô hiệu hóa tính năng này.

def kos_root(): 
    """Return the pathname of the KOS root directory.""" 
    global _kos_root 
    if _kos_root: return _kos_root 

Tất cả những gì bạn cần làm là thêm chuỗi trích dẫn gấp đôi ba trong mọi hàm.

Answer 4

Câu hỏi đặt ra là liệu bạn có thể vô hiệu hóa lỗi ping "chuỗi tài liệu mô-đun bị thiếu mô-đun" không. Câu trả lời cho câu hỏi này là Không. Pylint hiện không cho phép bạn phân biệt giữa cảnh báo chuỗi tài liệu (điều này rất khó chịu).

Tuy nhiên, tất cả không bị mất, tôi khuyên bạn nên sử dụng flake8 để kiểm tra tất cả các mã python. Họ thực sự có hành động của họ với nhau và tôi đã từ bỏ con tàu trăn từ lâu mà không có họ. Bạn có thể cài đặt tiện ích mở rộng chuỗi tài liệu bằng pip ->pip install flake8_docstrings. Nó sử dụng http://www.pydocstyle.org/en/latest/index.html.

Sau đó, bạn chỉ có thể sử dụng công tắc --ignore D100. Ví dụ: flake8 file.py --ignore D100

Answer 5

Đã muộn nhưng tôi vẫn thấy nó hữu ích. Vì vậy, chia sẻ. Tìm thấy số này here.

Bạn có thể thêm cờ "- chỉ dành cho khách hàng" để chặn thông báo.

Để thực hiện việc này, hãy chuyển đến cài đặt. Chỉnh sửa các dòng sau:

"python.linting.pylintArgs": []

Như

"python.linting.pylintArgs": ["--errors-only"]

Và bạn là tốt để đi!