docstring

This skill assists developers in maintaining high-quality, standardized documentation within the PyTorch repository. It automates the process of writing or updating docstrings for Python functions, methods, and C-bound APIs, ensuring strict adherence to the project's established conventions found in modules like torch._tensor_docs.py and torch.nn.functional. It is intended for software engineers and researchers contributing to the PyTorch codebase who need to document complex mathematical operations, tensor manipulations, or API changes while maintaining consistency across the library.

The skill provides structured guidance on implementing reStructuredText (reST) formatting, which is essential for proper Sphinx documentation rendering. It helps users structure the function signature, provide brief descriptions, include complex mathematical formulas using LaTeX math directives, and cross-reference related classes, methods, or attributes using proper Sphinx roles. By leveraging this tool, contributors can ensure that their documentation is not only readable but also technically accurate and discoverable via PyTorch's official documentation system.

• Standardizes function signature formatting, including return types and keyword-only argument separators (*).

• Ensures use of raw strings (r""") to prevent backslash escaping issues in LaTeX math expressions.

• Provides templates for Args, Keyword Args, and Returns sections with correct indentation and type annotation styles.

• Automates the inclusion of Examples blocks using standard >>> prompts to improve code readability and user testing.

• Handles the technical requirements for C-bound functions that utilize the _add_docstr helper function.

• Always include comprehensive Examples whenever a function or method is modified to demonstrate intended usage.

• Use accurate cross-references (e.g., :class:~torch.nn.Module) to link documentation components and improve navigation.

• Adhere to the specified admonition styles for notes and warnings to highlight critical numerical stability information, such as NLLLoss behaviors.

• Ensure mathematical expressions use the .. math:: directive for clarity and proper HTML/PDF rendering.

• Input for this skill should be the function or method implementation; output is a formatted, ready-to-insert docstring that follows all PyTorch repository style guidelines.