Fix all Sphinx build warnings/errors (19 -> 0) - #837
Merged
Merged
Conversation
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>
2 tasks
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 cleanbuild succeeded.What was found and fixed
docs/api/transformations.rst: a brokentoctreeblock referencingtextattack.transformations.{sentence_transformations,word_insertions,word_merges,word_swaps}as if this file lived indocs/apidoc/— but it's indocs/api/, so none of the four targets resolved (toctree contains reference to nonexisting document). Removed it; the same content is already reachable viadocs/apidoc/textattack.transformations.rst, linked fromindex.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 bothAttackArgsandModelEvalArgs) 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 theExample::block already used above it in the same docstring.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 fromlogit_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
build succeededwith zero warnings/errors (confirmed via-W --keep-going, both incrementally after each fix and as a final full clean rebuild)black --check/flake8clean on all changed files🤖 Generated with Claude Code