diff --git a/FAQ.md b/FAQ.md index 5ccb29256..bb166982a 100644 --- a/FAQ.md +++ b/FAQ.md @@ -6,6 +6,18 @@ Pylance is a language server, which provides features like IntelliSense, logical ### What features are in Pylance but not in Pyright? What is the difference exactly? Pylance has a handful of valuable features that are not available in Pyright, including semantic highlighting, refactoring code actions (extract variable/extract method), docstrings for built-in/standard library modules, and IntelliCode compatibility. Pylance also ships with a collection of type stubs for popular modules to provide fast and accurate auto-completions and type checking. +### How do I enable automatic docstring template generation? +Pylance includes built-in support for automatic docstring template generation. To enable this feature: +1. Open Settings (File > Preferences > Settings) +2. Search for `python.analysis.supportDocstringTemplate` +3. Enable the setting + +Once enabled, typing `"""` inside a function, class, or method will automatically generate a docstring template with parameters, return types, and other sections. Pylance supports multiple popular formats including Google style, NumPy style, and Sphinx style. + +For more details, see the [supportDocstringTemplate documentation](docs/settings/python_analysis_supportDocstringTemplate.md). + +**Note:** This feature is enabled by default in `full` language server mode. You can also use the autoDocstring extension for additional customization options. + ### Are there any plans to open-source Pylance in the future? Because we have plans to include Pylance in Microsoft products outside of VS Code that do not have the same license, business models and/or are closed-source (for example, fully managed products and services), we do not currently have plans to open-source Pylance. diff --git a/README.md b/README.md index 4204f0b40..9ec4cf500 100644 --- a/README.md +++ b/README.md @@ -396,17 +396,29 @@ Pylance provides users with the ability to customize their Python language suppo } ``` -- `python.analysis.supportDocstringTemplate` - - Enable/disable support for reStructuredText docstring generation. +- [`python.analysis.supportDocstringTemplate`](docs/settings/python_analysis_supportDocstringTemplate.md) + - Enable/disable automatic docstring template generation. When enabled, typing `"""` at a docstring position will automatically generate a template with parameter descriptions, return types, and other relevant sections. Supports multiple docstring styles including Google, NumPy, and Sphinx formats. - Default value: `false` (or `true` in `full` mode) - Accepted values: - - `true` - - `false` (default) + - `true`: Enables automatic docstring template generation + - `false` (default): Disables the feature - Example: ```python - def foo(arg): - """| Preferences > Settings) +2. Search for `python.analysis.supportDocstringTemplate` +3. Check the box to enable the feature + +### Using settings.json + +1. Open **Command Palette** (`Ctrl+Shift+P` or `Cmd+Shift+P` on Mac) +2. Type `Preferences: Open Settings (JSON)` and select it +3. Add the following line: + ```json + "python.analysis.supportDocstringTemplate": true + ``` + +## Choosing Your Docstring Style + +Pylance automatically detects and uses the appropriate docstring style based on your project's existing patterns. If no existing pattern is detected, it defaults to Google style. + +**Note:** While Pylance generates the template structure, you should customize the descriptions to accurately document your code's behavior. + +## Examples + +### Function with Multiple Parameters + +```python +def process_data(data, filters=None, normalize=True, output_format="json"): + """Process and transform the input data. + + Args: + data: The input data to process + filters: Optional filters to apply (default: None) + normalize: Whether to normalize the data (default: True) + output_format: The desired output format (default: "json") + + Returns: + The processed data in the specified format + """ + pass +``` + +### Class with Constructor + +```python +class DataProcessor: + """A class for processing data. + + Args: + config: Configuration dictionary + verbose: Enable verbose logging (default: False) + """ + + def __init__(self, config, verbose=False): + """Initialize the DataProcessor. + + Args: + config: Configuration dictionary + verbose: Enable verbose logging (default: False) + """ + pass +``` + +### Function with Type Hints + +When your function includes type hints, Pylance incorporates them into the generated docstring: + +```python +from typing import List, Optional + +def filter_items(items: List[str], pattern: Optional[str] = None) -> List[str]: + """Filter items based on a pattern. + + Args: + items: List of items to filter + pattern: Optional pattern to match (default: None) + + Returns: + Filtered list of items + """ + pass +``` + +## Performance Considerations + +The `python.analysis.supportDocstringTemplate` setting has minimal impact on performance since template generation only occurs when you type `"""` at a docstring position. It does not affect general IntelliSense or type checking performance. + +## Frequently Asked Questions + +### Q: Can I customize the docstring template format? + +**A:** The template format is determined by Pylance's built-in support for standard docstring styles. For advanced customization, you may want to use the [autoDocstring](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring) extension alongside Pylance. + +### Q: Does this work with existing docstrings? + +**A:** The template generation feature is designed for creating new docstrings. It will not modify or reformat existing docstrings. + +### Q: Can I trigger template generation after typing """? + +**A:** Yes, you can use the code action (Quick Fix) menu after typing `"""` to generate or regenerate the template. + +### Q: Does this feature work in Jupyter Notebooks? + +**A:** Yes, docstring template generation works in Jupyter Notebooks when using Pylance as your language server. + +### Q: What if my function signature changes? + +**A:** You'll need to manually update the docstring to reflect the new signature. The template generation only occurs when you first create the docstring. + +### Q: Does this replace the autoDocstring extension? + +**A:** Pylance's built-in docstring template generation provides basic functionality similar to autoDocstring. However, the autoDocstring extension may offer more customization options and advanced features. You can use them together or choose the one that best fits your workflow. + +## Related Settings + +- **[`python.analysis.languageServerMode`](python_analysis_languageServerMode.md)**: Controls the overall feature set of Pylance. Docstring template generation is enabled by default in `full` mode. +- **`python.analysis.aiCodeActions`**: When enabled with Copilot, provides AI-assisted docstring generation for more detailed documentation. + +--- + +*For more information on Pylance settings and customization, refer to the **[Pylance Settings and Customization](https://code.visualstudio.com/docs/python/settings-reference)** documentation.* + +--- + +*This document was generated with the assistance of AI and has been reviewed by humans for accuracy and completeness.* + +--- +