菜单
Automatically fix Sphinx documentation issues in any Azure SDK for Python package following Azure SDK Python documentation standards.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/Azure/azure-sdk-for-python --skill fix-sphinx命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
EXPERIMENTAL. Create and test a classify-and-route Azure AI Content Understanding pipeline for packets that contain multiple document types (e.g. invoice + bank statement + loan application in one PDF). Walks per-type schema authoring → outer classifier wiring → batch test → category-aware stdout summary using the typed ContentUnderstandingClient. Use when the user has mixed-document packets.
EXPERIMENTAL. Iteratively author and test a custom Azure AI Content Understanding analyzer for a folder of **document** files (PDFs, page images) of a single type. Walks layout extraction → schema authoring → validation → batch test → agent review → refine cycle using the typed ContentUnderstandingClient. Use when the user wants to author a custom analyzer for invoices, contracts, forms, or any other single-type document set.
Run a specific sample for the Azure AI Content Understanding SDK. Use when users want to run a particular sample like sample_analyze_url.py or sample_analyze_invoice.py.
基于 SOC 职业分类
| 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 (#)".