Create and maintain comprehensive technical documentation including API docs, docstrings, README files, user guides, and changelogs. Automatically update inline docstrings, CHANGELOG, and README when code changes. Use when writing or updating project documentation, code comments, or technical guides, or after any .py file is created or modified. Triggers on documentation requests, docstring creation, README updates, API documentation needs, code changes to .py files, function signature modifications, or new module creation.
cylam0070 星標2026年3月21日
職業
分類
技術文檔
技能內容
Overview
Create professional, comprehensive technical documentation following industry standards for docstrings, API documentation, user guides, and project files.
Quick Start
Identify documentation type needed (docstring, README, API docs, tutorial)
Use appropriate template from assets/templates/
Follow style guidelines in references/style_guide.md
Include concrete examples with expected outputs
Core Workflows
Writing Function Docstrings
Use Google-style docstrings for Python code:
Start with one-line summary: Brief description of what the function does
Add detailed description: Explain behavior, edge cases, important notes
Document Args: Type, description, and valid values for each parameter
相關技能
Document Returns: Return type and description
Document Raises: All exceptions that can be raised
Include Example: Working code example with expected output
Template structure:
def function_name(param1: type1, param2: type2 = default) -> return_type:
"""
Brief one-line summary.
Longer description explaining behavior, edge cases, or important
notes about the function.
Args:
param1: Description of param1
Additional details if needed (indent 4 spaces)
param2: Description of param2 (default: value)
Returns:
Description of return value
Raises:
ExceptionType: When this exception occurs
Example:
>>> result = function_name("test", param2=10)
>>> print(result)
expected output
Note:
Any important notes or warnings
"""
Use README template: Load assets/templates/readme_template.md
Fill required sections:
Project name and brief description
Features list
Installation instructions
Quick start example
Usage examples (basic and advanced)
Add optional sections as needed:
Configuration
API reference links
Contributing guidelines
License
Test all code examples: Ensure they work before including
Writing API Documentation
Load API template: Use assets/templates/api_reference_template.md
Document each function/class:
Signature with type hints
Parameter descriptions
Return value details
Raised exceptions
Working example
Organize by module: Group related functions together
Include navigation: Table of contents for large APIs
Creating Tutorial Guides
Load tutorial template: Use assets/templates/tutorial_template.md
Structure content:
Introduction (what they'll learn)
Prerequisites
Step-by-step instructions
Expected outputs after each step
Common issues and solutions
Next steps
Test tutorial: Follow your own steps to verify accuracy
Include troubleshooting: Address common problems
Maintaining Changelogs
Load CHANGELOG template: Use assets/templates/changelog_template.md
Follow Keep a Changelog format:
Group changes by type (Added, Changed, Deprecated, Removed, Fixed, Security)
Include version numbers and dates
Keep Unreleased section at top
Write clear descriptions: What changed and why it matters to users
Adding Code Comments
Comment guidelines:
Explain WHY, not WHAT (code shows what)
Document complex algorithms or non-obvious logic
Explain workarounds or hacks
Add context for future maintainers
Avoid obvious comments
Good comment examples:
# RSI calculation requires at least 'period' data points
# to establish initial average gain/loss
if len(prices) < period:
return None
# yfinance sometimes returns data in wrong timezone
# Must explicitly convert to UTC before saving
data.index = data.index.tz_convert('UTC')
Code Change Documentation Update
Trigger this workflow whenever .py files are created or modified as part of a code change task.
Identify changed .py files: Collect the list of new and modified Python files from the current task.
Detect changed public symbols: For each file, identify:
New public functions or classes (no leading underscore)
Modified public functions or classes (signature changed, body changed)
Deleted public functions or classes
Update inline docstrings: For every new or modified public function and class, write or update a Google-style docstring following the templates in this skill. Do not add docstrings to private symbols (_name) unless explicitly asked.
Update README if public interface changed: If any public function or class was added, removed, or had its signature changed, locate the relevant section in the module or project README and update it. If no README section covers the changed symbol, add one.
Append CHANGELOG entry: Load assets/templates/changelog_template.md. Append a new entry under [Unreleased] grouping changes by type: Added / Changed / Removed. One line per changed symbol — state what changed and why it matters to callers.
Log all documentation file changes: After updating docstrings, README, and CHANGELOG, invoke the agent-logging skill to log each file that was modified.
Scope rules:
Docstrings: update only the files that changed — do not sweep unrelated files
README: update only sections directly related to the changed public interface
CHANGELOG: one entry per code-change task, not one entry per file
Examples
Example 1: Adding Docstring to Data Fetching Function
Input: "Add docstring to this function that fetches stock data"
Process:
Identify function signature and parameters
Understand what the function does
Apply Google-style docstring template
Add example with real ticker
Document possible exceptions
Output:
def fetch_stock_data(ticker: str, period: str = "1y") -> pd.DataFrame:
"""
Fetch historical stock price data from Yahoo Finance.
Args:
ticker: Stock ticker symbol (e.g., "AAPL", "MSFT")
period: Time period for data (default: "1y")
Valid periods: 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max
Returns:
DataFrame with columns: Date, Open, High, Low, Close, Volume
Index is datetime, timezone-aware (UTC)
Raises:
ValueError: If ticker is invalid or empty
DataFetchError: If API request fails after retries
Example:
>>> data = fetch_stock_data("AAPL", period="6mo")
>>> print(data.head())
Open High Low Close Volume
2023-07-01 180.00 182.50 179.50 182.00 50000000
Note:
Data is fetched from Yahoo Finance and may have slight delays.
Historical data older than 10 years may be incomplete.
"""
Example 2: Creating Project README
Input: "Create README for my stock analysis project"
Process:
Load assets/templates/readme_template.md
Fill in project-specific information
Add installation instructions
Include quick start example
Add usage examples for key features
Test all code examples
Output: Complete README.md with:
Clear project description
Installation steps tested and verified
Quick start example that runs
Usage examples for main features
Links to detailed documentation
Example 3: Documenting API Response Capture Class
Input: "Document the ResponseCapturer class with all methods"
Process:
Write class-level docstring explaining purpose
Document constructor parameters
Add docstrings to all public methods
Include usage examples (decorator and context manager)
Document all raised exceptions
Output: Fully documented class with:
Class description and attributes
Constructor documentation
Method docstrings with examples
Usage patterns demonstrated
Exception documentation
Style Guidelines
Docstring Best Practices
Use present tense ("Returns" not "Will return")
Start with verb for functions ("Fetch", "Calculate", "Parse")
Start with noun for classes ("Handler for", "Manager that")
Keep first line under 80 characters
Use complete sentences with proper punctuation
Include type hints in signature, not docstring (Python 3.8+)
README Best Practices
Lead with what the project does (not what it is)
Show code before explaining it
Use relative links for internal docs
Keep quick start under 10 lines of code
Test all examples before publishing
Code Comment Best Practices
Place comments above the code they describe
Use # for single-line, """ for multi-line
Don't comment obvious code
Update comments when code changes
Remove commented-out code (use version control)
Advanced Features
Module Docstrings
For module-level documentation including attributes and examples, see docstring_examples.md.
Changelog Conventions
For semantic versioning and changelog best practices, see changelog_guide.md.