Leveraging Docstrings for Comprehensive Python Documentation

{
  "title": "Leveraging Docstrings for Comprehensive Python Documentation",
  "description": "Understand the importance of docstrings in Python and how to write effective documentation for functions and classes to facilitate better code understanding.",
  "category": "Python Cursor Rules",
  "rules": [
    {
      "name": "Mandatory Docstrings for Public Modules, Classes, and Functions",
      "description": "Ensure that all public modules, classes, and functions include docstrings to provide clear documentation of their purpose and usage.",
      "pattern": "^(def|class)\\s+\\w+",
      "condition": "missing_docstring",
      "action": "warn",
      "message": "Public modules, classes, and functions must have docstrings to describe their purpose and usage."
    },
    {
      "name": "One-Line Summary for Short Functions",
      "description": "Use a single-line docstring for functions that are simple and can be described succinctly.",
      "pattern": "^def\\s+\\w+\\(.*\\):\\n\\s+\"\"\".*\"\"\"",
      "condition": "docstring_length <= 72",
      "action": "info",
      "message": "Use a one-line docstring for simple functions that can be described succinctly."
    },
    {
      "name": "Multi-Line Docstrings for Complex Functions",
      "description": "Provide a multi-line docstring for functions that require detailed explanations, including descriptions of parameters, return values, and exceptions.",
      "pattern": "^def\\s+\\w+\\(.*\\):\\n\\s+\"\"\".*\\n.*\\n.*\"\"\"",
      "condition": "docstring_length > 72",
      "action": "info",
      "message": "Use a multi-line docstring for complex functions that require detailed explanations."
    },
    {
      "name": "Class Docstrings with Attributes Section",
      "description": "Include an 'Attributes' section in class docstrings to document public attributes, following the same formatting as function 'Args' sections.",
      "pattern": "^class\\s+\\w+\\(.*\\):\\n\\s+\"\"\".*\\n\\n\\s+Attributes:\\n.*\"\"\"",
      "condition": "has_public_attributes",
      "action": "info",
      "message": "Include an 'Attributes' section in class docstrings to document public attributes."
    },
    {
      "name": "Consistent Docstring Formatting",
      "description": "Adhere to the Google style guide for docstrings, ensuring consistent formatting across the codebase.",
      "pattern": "\"\"\".*\"\"\"",
      "condition": "not_google_style",
      "action": "warn",
      "message": "Docstrings should follow the Google style guide for consistent formatting."
    },
    {
      "name": "Docstring Line Length Limit",
      "description": "Limit all lines in docstrings to a maximum of 72 characters to maintain readability.",
      "pattern": "\"\"\".*\"\"\"",
      "condition": "line_length > 72",
      "action": "warn",
      "message": "Docstring lines should not exceed 72 characters for better readability."
    },
    {
      "name": "Update Docstrings with Code Changes",
      "description": "Ensure that docstrings are updated to reflect any changes in code functionality to prevent outdated documentation.",
      "pattern": "\"\"\".*\"\"\"",
      "condition": "outdated_docstring",
      "action": "warn",
      "message": "Update docstrings to reflect recent changes in code functionality."
    }
  ]
}