Skip to content

Fix all Sphinx build warnings/errors (19 -> 0) - #837

Merged
qiyanjun merged 1 commit into
QData:masterfrom
qiyanjun:fix/sphinx-doc-warnings
Aug 14, 2026
Merged

qiyanjun merged 1 commit into
QData:masterfrom
qiyanjun:fix/sphinx-doc-warnings

Conversation

@qiyanjun

Copy link
Copy Markdown
Member

Summary

Built the docs locally with sphinx -b html . _build/html -W --keep-going (warnings-as-errors, don't stop at the first one) and fixed everything it surfaced — 19 warnings/errors down to a clean build succeeded.

What was found and fixed

  • docs/api/transformations.rst: a broken toctree block referencing textattack.transformations.{sentence_transformations,word_insertions,word_merges,word_swaps} as if this file lived in docs/apidoc/ — but it's in docs/api/, so none of the four targets resolved (toctree contains reference to nonexisting document). Removed it; the same content is already reachable via docs/apidoc/textattack.transformations.rst, linked from index.rst.
  • textattack/attack_args.py: two .. note:: blocks nested directly under a docstring paragraph with no blank line before them (invalid RST nesting → Unexpected indentation). Also fixed a malformed :obj: `int` role (stray space breaks the role syntax) — turned out to be the actual cause of a separate ambiguous cross-reference warning (more than one target found for cross-reference 'num_examples_offset', matching both AttackArgs and ModelEvalArgs) once fixed.
  • textattack/constraints/.../learning_to_write.py: a docstring paragraph had one extra leading space versus its sibling paragraphs, so RST parsed it as an indented block quote.
  • textattack/transformations/.../back_transcription.py: a BibTeX citation block wasn't marked as a literal block, so RST tried (and failed) to parse its internal indentation as nested block-quotes/definition-lists. Marked it literal with ::, matching the Example:: block already used above it in the same docstring.
  • Five files ("Title underline too short"): extended each RST title underline to match its title's actual length. One of these (named_entity_recognition_goal_function_result.py) also had a real content bug: the module docstring title was misspelled (...RecognitionoalFunctionResult, missing the "G" in "Goal") and its one-line description was copy-pasted from logit_sum's file ("logit sum goal function Result") instead of describing this class.

Why this matters now

None of these had actually broken CI's docs build before, because .readthedocs.yaml's build config itself was broken first (see #836) — RTD's build was failing at the config/install step, before ever reaching Sphinx. Once #836 lands and RTD can actually run Sphinx, these are exactly the warnings that build would hit.

Verification

  • Clean local Sphinx build: build succeeded with zero warnings/errors (confirmed via -W --keep-going, both incrementally after each fix and as a final full clean rebuild)
  • All edited modules still import correctly (docstring edits don't affect runtime, but confirmed no syntax breakage)
  • black --check / flake8 clean on all changed files

🤖 Generated with Claude Code

Found by building docs locally with `-W --keep-going` (warnings as
errors, don't stop at first one) - this is what ReadTheDocs/CI's
docs build effectively enforces, but none of these had actually
broken the build since RTD's build itself was already broken (see the
.readthedocs.yaml fix). Confirmed clean rebuild after each fix;
`build succeeded` with zero warnings at the end.

- docs/api/transformations.rst: removed a broken toctree block
  (referenced textattack.transformations.{sentence_transformations,
  word_insertions,word_merges,word_swaps} as if this file lived in
  docs/apidoc/, but it's in docs/api/, so none of the four targets
  resolved). The same content is already reachable via
  docs/apidoc/textattack.transformations.rst, linked from index.rst.
- textattack/attack_args.py: two `.. note::` blocks nested directly
  under a docstring paragraph with no blank line separating them,
  which RST parses as invalid nested indentation; also fixed a
  malformed `:obj: `int`` role (stray space breaks role syntax) that
  turned out to be the actual cause of a separate "more than one
  target found for cross-reference 'num_examples_offset'" warning
  once fixed.
- textattack/constraints/.../learning_to_write.py: a docstring
  paragraph had one extra leading space versus its siblings, making
  RST treat it as an indented block quote.
- textattack/transformations/.../back_transcription.py: a BibTeX
  citation block wasn't marked as a literal block, so RST tried
  (and failed) to parse its internal indentation as nested
  block-quotes/definition-lists. Marked it literal with `::`,
  matching the pattern already used for the Example:: block above it.
- Five files ("Title underline too short"): extended each RST title
  underline to match its title's length.
  textattack/goal_function_results/custom/named_entity_recognition_goal_function_result.py
  also had a copy-paste bug: its module docstring title was misspelled
  ("...Recognitio_n_oalFunctionResult", missing the "G" in "Goal") and
  its one-line description was copied from logit_sum's file
  ("logit sum goal function Result") instead of describing this class.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@qiyanjun
qiyanjun merged commit a5e92f3 into QData:master Aug 14, 2026
6 checks passed
timothybrush pushed a commit to timothybrush/TextAttack that referenced this pull request Aug 14, 2026
Reviewed docs/0_get_started/, docs/1start/, and docs/3recipes/ for
outdated code examples, broken external links, and stale version/
count references. Each item verified against current code or a live
request before fixing:

- installation.md: "Python 3.6 or above" and the conda example's
  `python=3.8` are both stale; setup.py has required >=3.9 since the
  black-version-upgrade PR. Bumped both to 3.9.
- command_line_usage.md: `textattack eval-model` was renamed to
  `textattack eval` (confirmed against
  EvalModelCommand.register_subcommand's actual registered name).
- quick_api_tour.rst: fixed two cross-references pointing at a
  nonexistent `transformers.models.wrapper` module (should be
  `textattack.models.wrappers`), and a malformed `:ref:TextFooler
  attack` role with no matching target.
- what_is_an_adversarial_attack.md: a copy-pasteable CLI example had
  its `--flag` hyphens autocorrected to em-dashes at some point
  ("attack — model lstm-mr — num-examples..."), making it
  non-functional if pasted as-is. Restored `--`.
- support.md: pointed contributors at `transformation.rst`, which
  doesn't exist (it's `docs/api/transformations.rst`).
- FAQ.md / attacks4Components.md / attack_recipes_cmd.md: "16 adversarial
  attacks" is stale (confirmed 21 CLI-registered recipes via
  ATTACK_RECIPE_NAMES + 3 Python-only multi-lingual recipes = 24);
  added the missing `a2t`, `leap`, and French/Spanish/Chinese recipe
  rows to both HTML comparison tables, which listed neither despite
  both existing in the codebase.
- attack_recipes.rst: fixed a stale recipe-numbering gap (17-19 should
  have been 18-20 after an earlier recipe was inserted above without
  renumbering everything below it); now sequential 0-23.
- attack_recipes_cmd.md: the DeepWordBug example labeled "on DistilBERT
  trained on the Quora Question Pairs paraphrase identification
  dataset" used `distilbert-base-uncased-cola` (a *grammatical
  acceptability* model, unrelated to QQP/paraphrase); fixed to
  `distilbert-base-cased-qqp`, confirmed to exist on the Hub.
- models.md: `github.com/huggingface/nlp` is HuggingFace's old,
  renamed repo (confirmed it 301-redirects to
  `github.com/huggingface/datasets`); updated both link text and href.

Verified: full clean Sphinx rebuild afterward introduces no new
warnings in any of these files (cross-checked against the existing,
separately-tracked warning list from PR QData#837, which touches different
files entirely).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant