/document-public-apis

name: document-public-apis
description: Document undocumented public APIs in PyTorch by removing functions from coverage_ignore_functions and coverage_ignore_classes in docs/source/conf.py, running Sphinx coverage, and adding the appropriate autodoc directives to the correct .md or .rst doc files. Use when a user asks to remove functions from conf.py ignore lists.

Document Public APIs

This skill documents undocumented public APIs in PyTorch by removing entries from the coverage ignore lists in `docs/source/conf.py` and adding Sphinx autodoc directives (e.g., `autosummary`, `currentmodule`, `autoclass`, `automodule`) to the corresponding `.md` or `.rst` doc source files in `docs/source/`.

**"Documenting" means adding autodoc directives to doc source files — NEVER modifying Python source code.** Do not add or edit docstrings in `.py` files. Your only job is to add the correct directive to the correct doc file.

**IMPORTANT: Before adding any function to the sphinx doctree, verify it has a real docstring.** Use a quick Python check (e.g., `python -c "from torch.module import func; print(bool(func.__doc__))"`) to confirm the function has actual documentation content — not just an empty docstring or a bare `.. warning:: This API is experimental` stub. Functions without meaningful docstrings should be left in the `coverage_ignore_functions`/`coverage_ignore_classes` lists. Adding undocumented functions to the doctree creates empty or near-empty pages that degrade documentation quality.

Overview

`docs/source/conf.py` contains two lists that suppress Sphinx coverage warnings for undocumented APIs:

• `coverage_ignore_functions`: undocumented functions
• `coverage_ignore_classes`: undocumented classes

Entries are organized by **module comment groups**. Each group has a module label comment followed by the function/class names that belong to that module:

coverage_ignore_functions = [
    # torch.ao.quantization.fx.convert              <-- module label comment
    "convert",                                       # <-- entries belonging to this module
    "convert_custom_module",
    "convert_standalone_module",
    "convert_weighted_module",
    # torch.ao.quantization.fx.fuse                 <-- next module group
    "fuse",
    # torch.nn.functional
    "assert_int_or_pair",  # looks unintentionally public   <-- entry with inline comment
    "constant",  # deprecated                                <-- entry with inline comment
]

There are two kinds of comments:

• **Module label comments** (`# torch.ao.quantization.fx.convert`): these label which module the entries below belong to. They appear on their own line before a group of entries.
• **Inline comments** (`# deprecated`, `# documented as adaptive_max_pool1d`): these appear after a string entry on the same line and explain *why* the entry is in the ignore list.

The module label comment directly tells you: 1. Which module the functions belong to 2. Where to add them in the docs (e.g., `# torch.ao.quantization.fx.convert` → the functions go under `torch.ao.quantization.fx.convert` in the doc file)

Instructions

Each invocation of this skill processes **one batch** of module groups. Pick one or more complete module groups from the ignore lists, document their functions, and verify.

Step 1: Select module groups to document

Read `docs/source/conf.py` and select one or more **complete module groups** to document. A module group is a module label comment and all entries beneath it up to the next module label comment. Process entire groups — never split a group across batches.

For example, selecting the `torch.ao.quantization.fx.convert` group means taking all of:

# torch.ao.quantization.fx.convert
"convert",
"convert_custom_module",
"convert_standalone_module",
"convert_weighted_module",

Work through the lists top-to-bottom. Choose enough groups to make meaningful progress (aim for 5–15 functions total, but always include complete groups even if that means going slightly over).

**Check inline comments before including an entry.** Some entries have inline comments that indicate they should not be documented:

• `# deprecated` — The function is deprecated. Leave it in the ignore list.
• `# documented as <other_name>` — Already documented under a different name. Leave it.
• `# looks unintentionally public` — Probably not meant to be public API. Leave it.
• `# legacy helper for ...` — Same as deprecated. Leave it.
• `# utility function` - Leave it.

If a module group has a **mix** of regular entries and entries with inline comments, still process the group — but only comment out the regular entries. Leave entries with inline comments untouched in the ignore list.

Step 1b: Verify functions have actual docstrings

For each function selected in Step 1, check that it has a meaningful docstring by running:

python -c "from torch.module.path import func_name; doc = func_name.__doc__; print('HAS DOC' if doc and len(doc.strip()) > 80 else 'NO DOC'); print(repr(doc[:120]) if doc else 'None')"

A function has a **meaningful docstring** if it has real descriptive content — not just:

• `None` or empty string
• Only a `.. warning:: This API is experimental` stub with no description
• Only a one-line auto-generated signature

**Functions without meaningful docstrings must stay in the ignore list.** Remove them from your batch. If an entire module group has no functions with docstrings, skip the whole group.

Step 2: Present the batch to the user

**Before making any edits**, present the selected module groups and their functions to the user. Indicate which functions passed the docstring check and which were excluded. Show them organized by module:

Module: torch.ao.quantization.fx.convert
  - convert
  - convert_custom_module
  - convert_standalone_module
  - convert_weighted_module

Module: torch.ao.quantization.fx.fuse
  - fuse

Then use the `AskUserQuestion` tool to let the