en un clic
fix-sphinx
// Automatically fix Sphinx documentation issues in any Azure SDK for Python package following Azure SDK Python documentation standards.
// Automatically fix Sphinx documentation issues in any Azure SDK for Python package following Azure SDK Python documentation standards.
Automate bumping typespec-python version in emitter-package.json for the Azure SDK for Python repository. Use this skill when the user wants to update @azure-tools/typespec-python to the latest version, create a PR for the version bump, or manage emitter-package.json updates.
A simple greeting skill that confirms the agent is running correctly.
Post-regeneration customization guide for azure-search-documents. Verifies _patch.py imports, ApiVersion, enum aliases, validation, testing, and changelog after codegen. WHEN: regenerate azure-search-documents; azure-search-documents tsp-client update; update azure-search-documents API version; reconcile azure-search-documents _patch.py after regeneration; fix azure-search-documents regeneration break; prepare azure-search-documents release after regeneration.
Interactive wizard that walks service teams through creating a package-specific skill for their Azure SDK package. Scans the package, detects customization patterns, scaffolds a SKILL.md with references, validates with vally lint, and registers in find-package-skill. WHEN: create package skill; add service skill; bootstrap skill for package; new package skill; skill for my SDK package; write skill for search; write skill for cosmos.
Automatically fix black code formatting issues in any Azure SDK for Python package
Automatically fix mypy type checking issues in any Azure SDK for Python package following Azure SDK Python patterns.
| name | fix-sphinx |
| description | Automatically fix Sphinx documentation issues in any Azure SDK for Python package following Azure SDK Python documentation standards. |
This skill automatically fixes Sphinx documentation warnings and errors in any Azure SDK for Python package by analyzing existing documentation patterns and applying fixes with 100% confidence.
Intelligently fixes Sphinx documentation issues by:
Command:
cd <package-path>
azpysdk --isolate sphinx .
Note:
azpysdk sphinxruns Sphinx documentation build for the package. This checks for documentation warnings and errors.
Using Latest Sphinx:
azpysdk --isolate next-sphinx .
Use
azpysdk next-sphinxto run with the latest version of Sphinx. This is useful for catching issues that may be flagged by newer Sphinx versions.
Check if user provided in their request:
https://github.com/Azure/azure-sdk-for-python/issues/... in user's message)sdk/storage/azure-storage-blob or azure-storage-blob)If both GitHub issue URL and package path are missing: Ask: "Please provide either the GitHub issue URL or the package path (e.g. sdk/storage/azure-storage-blob) for the Sphinx documentation problems you want to fix."
If a GitHub issue URL is provided: Read the issue to understand which package and documentation files/modules are affected, and the specific warnings to fix.
If only a package path is provided: Run Sphinx checks directly on the package.
If virtual environment is missing: Ask: "Do you have an existing virtual environment path, or should I create 'env'?"
IMMEDIATELY activate the virtual environment before ANY other command:
# Activate the provided virtual environment (e.g., env, venv)
.\<venv-name>\Scripts\Activate.ps1
# If creating new virtual environment:
python -m venv env
.\env\Scripts\Activate.ps1
⚠️ IMPORTANT: ALL subsequent commands MUST run within the activated virtual environment. Never run commands outside the venv.
# Navigate to the package directory (within activated venv)
cd <package-path>
# Install dev dependencies from dev_requirements.txt (within activated venv)
pip install -r dev_requirements.txt
# Install the package in editable mode (within activated venv)
pip install -e .
Based on the GitHub issue details, determine which documentation files to check:
Option A - Run Sphinx on the package and review output:
# Ensure you're in the package directory (within activated venv)
cd <package-path>
# Run Sphinx build on the package
azpysdk --isolate sphinx .
# Review output for warnings/errors in the specific files/modules mentioned in the issue
Option B - Check modified documentation files (if no specific target):
git diff --name-only HEAD | Select-String "\.py$|\.rst$|\.md$" | Select-String "<package-path>"
git diff --cached --name-only | Select-String "\.py$|\.rst$|\.md$" | Select-String "<package-path>"
⚠️ Ensure virtual environment is still activated before running:
# Navigate to the package directory
cd <package-path>
# Run Sphinx build on the package (within activated venv)
azpysdk --isolate sphinx .
# Review output for the specific files/modules from the issue
Parse the Sphinx output to identify:
Before fixing, search the codebase for how similar documentation is handled:
# Example: Search for similar docstring patterns
grep -r "docstring_pattern" <package-path>/
grep -r ":param" <package-path>/
grep -r ":return:" <package-path>/
Use the existing documentation patterns to ensure consistency.
ALLOWED ACTIONS: ✅ Fix documentation warnings/errors with 100% confidence ✅ Use existing documentation patterns as reference ✅ Follow Azure SDK Python documentation guidelines ✅ Make minimal, targeted changes to docstrings ✅ Add missing docstrings following existing patterns ✅ Fix malformed docstring syntax ✅ Correct parameter and return type documentation
FORBIDDEN ACTIONS: ❌ Fix warnings without complete confidence ❌ Create new documentation files for solutions ❌ Import non-existent modules in documentation ❌ Add new dependencies or imports ❌ Make unnecessary large changes ❌ Change code logic without clear reason ❌ Delete documentation without clear justification
Re-run Sphinx to ensure:
Provide a summary:
⚠️ REQUIRED when a GitHub issue URL was provided: You MUST create a pull request after validating fixes. This is not optional.
Create a pull request with a descriptive title and body referencing the issue. Include what was fixed and confirm all Sphinx documentation checks pass. The PR title should follow the format: "fix(): Resolve sphinx errors (#)".