From 45b8f49b0eb8b090e15586a29e088fcd1c372b9e Mon Sep 17 00:00:00 2001 From: Yanjun Qi / Jane Date: Fri, 14 Aug 2026 17:09:57 -0400 Subject: [PATCH] Fix all Sphinx build warnings/errors (19 -> 0) 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 --- docs/api/transformations.rst | 10 ---------- textattack/attack_args.py | 4 +++- .../learning_to_write/learning_to_write.py | 2 +- textattack/goal_function_results/custom/__init__.py | 2 +- .../named_entity_recognition_goal_function_result.py | 6 +++--- .../custom/targeted_bonus_goal_function_result.py | 2 +- .../custom/targeted_strict_goal_function_result.py | 2 +- textattack/loggers/json_summary_logger.py | 2 +- .../sentence_transformations/back_transcription.py | 2 +- 9 files changed, 12 insertions(+), 20 deletions(-) diff --git a/docs/api/transformations.rst b/docs/api/transformations.rst index 508e46a6d..ab6761bdc 100644 --- a/docs/api/transformations.rst +++ b/docs/api/transformations.rst @@ -11,13 +11,3 @@ Composite Transformation .. autoclass:: textattack.transformations.CompositeTransformation :members: - - -.. toctree:: - :maxdepth: 6 - - textattack.transformations.sentence_transformations - textattack.transformations.word_insertions - textattack.transformations.word_merges - textattack.transformations.word_swaps - diff --git a/textattack/attack_args.py b/textattack/attack_args.py index 21b144c5d..1ce0a006d 100644 --- a/textattack/attack_args.py +++ b/textattack/attack_args.py @@ -154,9 +154,10 @@ class AttackArgs: The number of successful adversarial examples we want. This is different from :obj:`num_examples` as :obj:`num_examples` only cares about attacking `N` samples while :obj:`num_successful_examples` aims to keep attacking until we have `N` successful cases. + .. note:: If set, this argument overrides `num_examples` argument. - num_examples_offset (:obj: `int`, `optional`, defaults to :obj:`0`): + num_examples_offset (:obj:`int`, `optional`, defaults to :obj:`0`): The offset index to start at in the dataset. attack_n (:obj:`bool`, `optional`, defaults to :obj:`False`): Whether to run attack until total of `N` examples have been attacked (and not skipped). @@ -167,6 +168,7 @@ class AttackArgs: query_budget (:obj:`int`, `optional`, defaults to :obj:`None`): The maximum number of model queries allowed per example attacked. If not set, we use the query budget set in the :class:`~textattack.goal_functions.GoalFunction` object (which by default is :obj:`float("inf")`). + .. note:: Setting this overwrites the query budget set in :class:`~textattack.goal_functions.GoalFunction` object. checkpoint_interval (:obj:`int`, `optional`, defaults to :obj:`None`): diff --git a/textattack/constraints/grammaticality/language_models/learning_to_write/learning_to_write.py b/textattack/constraints/grammaticality/language_models/learning_to_write/learning_to_write.py index 9fb9f9bb0..ca40693d2 100644 --- a/textattack/constraints/grammaticality/language_models/learning_to_write/learning_to_write.py +++ b/textattack/constraints/grammaticality/language_models/learning_to_write/learning_to_write.py @@ -24,7 +24,7 @@ class LearningToWriteLanguageModel(LanguageModelConstraint): https://github.com/windweller/l2w - Reused by Jia et al., 2019, as a substitution for the Google + Reused by Jia et al., 2019, as a substitution for the Google 1-billion words language model (in a revised version the attack of Alzantot et al., 2018). diff --git a/textattack/goal_function_results/custom/__init__.py b/textattack/goal_function_results/custom/__init__.py index ac46cd788..147ebcf85 100644 --- a/textattack/goal_function_results/custom/__init__.py +++ b/textattack/goal_function_results/custom/__init__.py @@ -1,6 +1,6 @@ """ Custom Goal Function Result package: -============================= +==================================== Custom goal function results diff --git a/textattack/goal_function_results/custom/named_entity_recognition_goal_function_result.py b/textattack/goal_function_results/custom/named_entity_recognition_goal_function_result.py index fdb4ac121..182797d4e 100644 --- a/textattack/goal_function_results/custom/named_entity_recognition_goal_function_result.py +++ b/textattack/goal_function_results/custom/named_entity_recognition_goal_function_result.py @@ -1,9 +1,9 @@ """ -NamedEntityRecognitionoalFunctionResult Class -==================================== +NamedEntityRecognitionGoalFunctionResult Class +=============================================== -logit sum goal function Result +named entity recognition goal function Result """ diff --git a/textattack/goal_function_results/custom/targeted_bonus_goal_function_result.py b/textattack/goal_function_results/custom/targeted_bonus_goal_function_result.py index 08aa48223..1a82734cb 100644 --- a/textattack/goal_function_results/custom/targeted_bonus_goal_function_result.py +++ b/textattack/goal_function_results/custom/targeted_bonus_goal_function_result.py @@ -1,7 +1,7 @@ """ TargetedBonusGoalFunctionResult Class -==================================== +===================================== targeted bonus goal function Result diff --git a/textattack/goal_function_results/custom/targeted_strict_goal_function_result.py b/textattack/goal_function_results/custom/targeted_strict_goal_function_result.py index 6c1b6f786..885b67e58 100644 --- a/textattack/goal_function_results/custom/targeted_strict_goal_function_result.py +++ b/textattack/goal_function_results/custom/targeted_strict_goal_function_result.py @@ -1,7 +1,7 @@ """ TargetedStrictGoalFunctionResult Class -==================================== +====================================== targeted strict goal function Result diff --git a/textattack/loggers/json_summary_logger.py b/textattack/loggers/json_summary_logger.py index b1ac508dd..9b6b06481 100644 --- a/textattack/loggers/json_summary_logger.py +++ b/textattack/loggers/json_summary_logger.py @@ -1,6 +1,6 @@ """ Attack Summary Results Logs to Json -======================== +=================================== """ import json diff --git a/textattack/transformations/sentence_transformations/back_transcription.py b/textattack/transformations/sentence_transformations/back_transcription.py index c902b6d52..a7eba18c9 100644 --- a/textattack/transformations/sentence_transformations/back_transcription.py +++ b/textattack/transformations/sentence_transformations/back_transcription.py @@ -34,7 +34,7 @@ class BackTranscription(SentenceTransformation): >>> augmenter.augment(s) - You can find more about the back transcription method in the following paper: + You can find more about the back transcription method in the following paper:: @inproceedings{kubis-etal-2023-back, title = "Back Transcription as a Method for Evaluating Robustness of Natural Language Understanding Models to Speech Recognition Errors",