skills.rest
pytorch
pytorchOFFICIAL
Explore all skills by this author →
WebsiteGitHub

document-public-apis

Document undocumented PyTorch public APIs by adding Sphinx autodoc directives to doc source files.

103k|29.1k|Updated Aug 13, 2016
Search Tags:#restructuredtext#Documentation#Sphinx#autodoc#pyTorch#conf.py#API coverage
One-click install
npx skills add https://github.com/pytorch/pytorch --skill document-public-apis
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: document-public-apis
Source: https://github.com/pytorch/pytorch/tree/main/.claude/skills/document-public-apis
Command: npx skills add https://github.com/pytorch/pytorch --skill document-public-apis

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

PyTorch's Sphinx documentation build emits coverage warnings for public APIs that lack autodoc directives, leaving gaps in the official reference. This Skill systematically removes entries from the coverage_ignore_functions and coverage_ignore_classes lists in docs/source/conf.py and inserts the correct automodule, currentmodule, autofunction, and autoclass directives into the matching .md or .rst files under docs/source/.

Core Features & Use Cases

  • Batch Processing of Module Groups: Selects complete module groups from the ignore lists, verifies each function has a real docstring, and processes them in batches of 5–15 functions.
  • Docstring Verification: Runs a Python check to confirm each function has meaningful documentation content before adding it to the doctree, avoiding empty or stub-only pages.
  • Sphinx Coverage Verification: Runs make coverage and reads docs/build/coverage/python.txt to confirm 100% coverage across all modules before cleaning up commented-out entries.
  • Use Case: A PyTorch maintainer wants to close documentation gaps for torch.ao.quantization.fx.convert. Use this Skill to remove those functions from the ignore list, add the proper automodule and autofunction directives to the corresponding doc file, and verify the coverage report shows zero undocumented APIs.

Quick Start

Use the document-public-apis skill to document the next batch of undocumented functions from the coverage ignore lists in docs/source/conf.py.

Frequently Asked Questions about document-public-apis

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I document undocumented PyTorch public APIs in Sphinx?▼

Remove the function or class from `coverage_ignore_functions` or `coverage_ignore_classes` in `docs/source/conf.py`, then add `automodule`, `currentmodule`, and `autofunction` or `autoclass` directives to the matching `.md` or `.rst` file under `docs/source/`. Run `make coverage` to verify 100% coverage.

What is the difference between MyST Markdown and reStructuredText autodoc directives in PyTorch docs?▼

MyST Markdown files (`.md`) wrap directives in ````{eval-rst}` fences, while reStructuredText files (`.rst`) use bare directives. Both require `automodule` and `currentmodule` before `autofunction` or `autoclass` with short names.

Why does Sphinx coverage show undocumented functions after adding directives?▼

Common causes include adding the directive to the wrong doc file, using the wrong directive type (e.g., `autofunction` for a class), or a missing `automodule` for an unregistered submodule. Re-run `make coverage` after each fix.

Can I document PyTorch functions that only have experimental warning stubs?▼

No. Functions with only a `.. warning:: This API is experimental` stub and no descriptive content should remain in the ignore list. Adding them creates empty documentation pages that degrade quality.

When should I skip entries in the coverage ignore lists?▼

Skip entries with inline comments like `# deprecated`, `# documented as <other_name>`, `# looks unintentionally public`, or `# legacy helper`. These indicate the function should not appear in the public docs.

Related Skills

Explore More Software Engineering Skills→
mk-knight23mk-knight23
1

doc-generator

Generate MkDocs or Sphinx documentation and docstrings from Python source code.

Community
Advanced
DirtybitGamesDirtybitGames
15

demo-page

Convert a Markdown source document into an HTML demo page and deploy it to the gh-pages branch.

Official
Intermediate
fredericosantosfredericosantos
1

just-init

Generate and refresh __init__.py docstrings to reflect Python package structure.

Community
Intermediate
VoldemortGinVoldemortGin

documenting-python-libraries

Generate Google-style docstrings and configure Sphinx with ReadTheDocs for Python libraries.

Community
Intermediate