Update sphinx and improve documentation (#720)

* Update sphinx version * Fix citations in docs
bethgelab · Mar 4, 2024 · bf22155 · bf22155
1 parent bb56af1
commit bf22155
Show file tree

Hide file tree

Showing 7 changed files with 38 additions and 108 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -19,7 +19,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "Foolbox"
-copyright = "2021, Jonas Rauber, Roland S. Zimmermann"
+copyright = "2024, Jonas Rauber, Roland S. Zimmermann"
 author = "Jonas Rauber, Roland S. Zimmermann"
 
 version = foolbox.__version__

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,4 +1,4 @@
-sphinx==4.5.0
-sphinx-autobuild==2021.3.14
-sphinx_rtd_theme==1.0.0
+sphinx>=7.2.6
+sphinx-autobuild>=2024.2.4
+sphinx_rtd_theme>=2.0.0
 sphinx-typlog-theme==0.8.0
diff --git a/foolbox/attacks/additive_noise.py b/foolbox/attacks/additive_noise.py
@@ -119,13 +119,7 @@ class L2ClippingAwareAdditiveGaussianNoiseAttack(
 ):
     """Samples Gaussian noise with a fixed L2 size after clipping.
 
-    The implementation is based on [#Rauber20]_.
-
-    References:
-        .. [#Rauber20] Jonas Rauber, Matthias Bethge
-            "Fast Differentiable Clipping-Aware Normalization and Rescaling"
-            https://arxiv.org/abs/2007.07677
-
+    The implementation is based on [Rauber20]_.
     """
 
     pass
@@ -136,10 +130,10 @@ class L2ClippingAwareAdditiveUniformNoiseAttack(
 ):
     """Samples uniform noise with a fixed L2 size after clipping.
 
-    The implementation is based on [#Rauber20]_.
+    The implementation is based on [Rauber20]_.
 
     References:
-        .. [#Rauber20] Jonas Rauber, Matthias Bethge
+        .. [Rauber20] Jonas Rauber, Matthias Bethge
             "Fast Differentiable Clipping-Aware Normalization and Rescaling"
             https://arxiv.org/abs/2007.07677
 
@@ -242,12 +236,7 @@ class L2ClippingAwareRepeatedAdditiveGaussianNoiseAttack(
 ):
     """Repeatedly samples Gaussian noise with a fixed L2 size after clipping.
 
-    The implementation is based on [#Rauber20]_.
-
-    References:
-        .. [#Rauber20] Jonas Rauber, Matthias Bethge
-            "Fast Differentiable Clipping-Aware Normalization and Rescaling"
-            https://arxiv.org/abs/2007.07677
+    The implementation is based on [Rauber20]_.
 
     Args:
         repeats : How often to sample random noise.
@@ -262,12 +251,7 @@ class L2ClippingAwareRepeatedAdditiveUniformNoiseAttack(
 ):
     """Repeatedly samples uniform noise with a fixed L2 size after clipping.
 
-    The implementation is based on [#Rauber20]_.
-
-    References:
-        .. [#Rauber20] Jonas Rauber, Matthias Bethge
-            "Fast Differentiable Clipping-Aware Normalization and Rescaling"
-            https://arxiv.org/abs/2007.07677
+    The implementation is based on [Rauber20]_.
 
     Args:
         repeats : How often to sample random noise.

diff --git a/foolbox/attacks/brendel_bethge.py b/foolbox/attacks/brendel_bethge.py
@@ -294,7 +294,7 @@ def optimize_boundary_s_t_trustregion(self, x0, x, b, min_, max_, c, r):
 
 
 class BrendelBethgeAttack(MinimizationAttack, ABC):
-    """Base class for the Brendel & Bethge adversarial attack [#Bren19]_, a powerful
+    """Base class for the Brendel & Bethge adversarial attack [Bren19]_, a powerful
     gradient-based adversarial attack that follows the adversarial boundary
     (the boundary between the space of adversarial and non-adversarial images as
     defined by the adversarial criterion) to find the minimum distance to the
@@ -331,13 +331,6 @@ class BrendelBethgeAttack(MinimizationAttack, ABC):
             runs/CURRENT_DATETIME_HOSTNAME.
         binary_search_steps : Number of binary search steps used to find the adversarial boundary
             between the starting point and the clean image.
-
-    References:
-        .. [#Bren19] Wieland Brendel, Jonas Rauber, Matthias Kümmerer,
-            Ivan Ustyuzhaninov, Matthias Bethge,
-            "Accurate, reliable and fast robustness evaluation",
-            33rd Conference on Neural Information Processing Systems (2019)
-            https://arxiv.org/abs/1907.01003
     """
 
     def __init__(
@@ -604,7 +597,7 @@ def best_other_classes(logits: ep.Tensor, exclude: ep.Tensor) -> ep.Tensor:
 
 
 class L2BrendelBethgeAttack(BrendelBethgeAttack):
-    """L2 variant of the Brendel & Bethge adversarial attack. [#Bren19]_
+    """L2 variant of the Brendel & Bethge adversarial attack. [Bren19]_
     This is a powerful gradient-based adversarial attack that follows the
     adversarial boundary (the boundary between the space of adversarial and
     non-adversarial images as defined by the adversarial criterion) to find
@@ -613,11 +606,11 @@ class L2BrendelBethgeAttack(BrendelBethgeAttack):
     This is the reference implementation of the Brendel & Bethge attack.
 
     References:
-        .. [#Bren19] Wieland Brendel, Jonas Rauber, Matthias Kümmerer,
-           Ivan Ustyuzhaninov, Matthias Bethge,
-           "Accurate, reliable and fast robustness evaluation",
-           33rd Conference on Neural Information Processing Systems (2019)
-           https://arxiv.org/abs/1907.01003
+        .. [Bren19] Wieland Brendel, Jonas Rauber, Matthias Kümmerer,
+            Ivan Ustyuzhaninov, Matthias Bethge,
+            "Accurate, reliable and fast robustness evaluation",
+            33rd Conference on Neural Information Processing Systems (2019)
+            https://arxiv.org/abs/1907.01003
     """
 
     distance = l2
@@ -647,20 +640,13 @@ def mid_points(
 
 
 class LinfinityBrendelBethgeAttack(BrendelBethgeAttack):
-    """L-infinity variant of the Brendel & Bethge adversarial attack. [#Bren19]_
+    """L-infinity variant of the Brendel & Bethge adversarial attack. [Bren19]_
     This is a powerful gradient-based adversarial attack that follows the
     adversarial boundary (the boundary between the space of adversarial and
     non-adversarial images as defined by the adversarial criterion) to find
     the minimum distance to the clean image.
 
     This is the reference implementation of the Brendel & Bethge attack.
-
-    References:
-        .. [#Bren19] Wieland Brendel, Jonas Rauber, Matthias Kümmerer,
-           Ivan Ustyuzhaninov, Matthias Bethge,
-           "Accurate, reliable and fast robustness evaluation",
-           33rd Conference on Neural Information Processing Systems (2019)
-           https://arxiv.org/abs/1907.01003
     """
 
     distance = linf
@@ -694,20 +680,13 @@ def mid_points(
 
 
 class L1BrendelBethgeAttack(BrendelBethgeAttack):
-    """L1 variant of the Brendel & Bethge adversarial attack. [#Bren19]_
+    """L1 variant of the Brendel & Bethge adversarial attack. [Bren19]_
     This is a powerful gradient-based adversarial attack that follows the
     adversarial boundary (the boundary between the space of adversarial and
     non-adversarial images as defined by the adversarial criterion) to find
     the minimum distance to the clean image.
 
     This is the reference implementation of the Brendel & Bethge attack.
-
-    References:
-        .. [#Bren19] Wieland Brendel, Jonas Rauber, Matthias Kümmerer,
-           Ivan Ustyuzhaninov, Matthias Bethge,
-           "Accurate, reliable and fast robustness evaluation",
-           33rd Conference on Neural Information Processing Systems (2019)
-           https://arxiv.org/abs/1907.01003
     """
 
     distance = l1
@@ -741,20 +720,13 @@ def mid_points(
 
 
 class L0BrendelBethgeAttack(BrendelBethgeAttack):
-    """L0 variant of the Brendel & Bethge adversarial attack. [#Bren19]_
+    """L0 variant of the Brendel & Bethge adversarial attack. [Bren19]_
     This is a powerful gradient-based adversarial attack that follows the
     adversarial boundary (the boundary between the space of adversarial and
     non-adversarial images as defined by the adversarial criterion) to find
     the minimum distance to the clean image.
 
     This is the reference implementation of the Brendel & Bethge attack.
-
-    References:
-        .. [#Bren19] Wieland Brendel, Jonas Rauber, Matthias Kümmerer,
-           Ivan Ustyuzhaninov, Matthias Bethge,
-           "Accurate, reliable and fast robustness evaluation",
-           33rd Conference on Neural Information Processing Systems (2019)
-           https://arxiv.org/abs/1907.01003
     """
 
     distance = l0

diff --git a/foolbox/attacks/fast_minimum_norm.py b/foolbox/attacks/fast_minimum_norm.py
@@ -25,7 +25,7 @@ def best_other_classes(logits: ep.Tensor, exclude: ep.Tensor) -> ep.Tensor:
 
 
 def project_onto_l1_ball(x: ep.Tensor, eps: ep.Tensor) -> ep.Tensor:
-    """Computes Euclidean projection onto the L1 ball for a batch. [#Duchi08]_
+    """Computes Euclidean projection onto the L1 ball for a batch. [Duchi08]_
 
     Adapted from the pytorch version by Tony Duan:
     https://gist.github.com/tonyduan/1329998205d88c566588e57e3e2c0c55
@@ -35,7 +35,7 @@ def project_onto_l1_ball(x: ep.Tensor, eps: ep.Tensor) -> ep.Tensor:
         eps: radius of l-1 ball to project onto
 
     References:
-      ..[#Duchi08] Efficient Projections onto the l1-Ball for Learning in High Dimensions
+      ..[Duchi08] Efficient Projections onto the l1-Ball for Learning in High Dimensions
          John Duchi, Shai Shalev-Shwartz, Yoram Singer, and Tushar Chandra.
          International Conference on Machine Learning (ICML 2008)
     """
@@ -63,7 +63,7 @@ def project_onto_l1_ball(x: ep.Tensor, eps: ep.Tensor) -> ep.Tensor:
 
 
 class FMNAttackLp(MinimizationAttack, ABC):
-    """The Fast Minimum Norm adversarial attack, in Lp norm. [#Pintor21]_
+    """The Fast Minimum Norm adversarial attack, in Lp norm. [Pintor21]_
 
     Args:
         steps: Number of iterations.
@@ -80,13 +80,6 @@ class FMNAttackLp(MinimizationAttack, ABC):
         binary_search_steps: Number of steps to use for the search
             from the adversarial points. If no initial attack or adversarial
             starting point is provided, this parameter will be ignored.
-
-    References:
-        .. [#Pintor21] Maura Pintor, Fabio Roli, Wieland Brendel,
-            Battista Biggio, "Fast Minimum-norm Adversarial
-            Attacks through Adaptive Norm Constraints."
-            arXiv preprint arXiv:2102.12827 (2021).
-            https://arxiv.org/abs/2102.12827
     """
 
     def __init__(
@@ -310,7 +303,7 @@ def mid_points(
 
 
 class L1FMNAttack(FMNAttackLp):
-    """The L1 Fast Minimum Norm adversarial attack, in Lp norm. [#Pintor21L1]_
+    """The L1 Fast Minimum Norm adversarial attack, in Lp norm. [Pintor21]_
 
     Args:
         steps: Number of iterations.
@@ -329,10 +322,11 @@ class L1FMNAttack(FMNAttackLp):
             starting point is provided, this parameter will be ignored.
 
     References:
-        .. [#Pintor21L1] Maura Pintor, Fabio Roli, Wieland Brendel,
+        .. [Pintor21] Maura Pintor, Fabio Roli, Wieland Brendel,
             Battista Biggio, "Fast Minimum-norm Adversarial
             Attacks through Adaptive Norm Constraints."
             arXiv preprint arXiv:2102.12827 (2021).
+            https://arxiv.org/abs/2102.12827
     """
 
     distance = l1
@@ -370,7 +364,7 @@ def mid_points(
 
 
 class L2FMNAttack(FMNAttackLp):
-    """The L2 Fast Minimum Norm adversarial attack, in Lp norm. [#Pintor21L2]_
+    """The L2 Fast Minimum Norm adversarial attack, in Lp norm. [Pintor21]_
 
     Args:
         steps: Number of iterations.
@@ -387,13 +381,6 @@ class L2FMNAttack(FMNAttackLp):
         binary_search_steps: Number of steps to use for the search
             from the adversarial points. If no initial attack or adversarial
             starting point is provided, this parameter will be ignored.
-
-    References:
-        .. [#Pintor21L2] Maura Pintor, Fabio Roli, Wieland Brendel,
-            Battista Biggio, "Fast Minimum-norm Adversarial
-            Attacks through Adaptive Norm Constraints."
-            arXiv preprint arXiv:2102.12827 (2021).
-            https://arxiv.org/abs/2102.12827
     """
 
     distance = l2
@@ -429,7 +416,7 @@ def mid_points(
 
 
 class LInfFMNAttack(FMNAttackLp):
-    """The L-infinity Fast Minimum Norm adversarial attack, in Lp norm. [#Pintor21Linf]_
+    """The L-infinity Fast Minimum Norm adversarial attack, in Lp norm. [Pintor21]_
 
     Args:
         steps: Number of iterations.
@@ -446,13 +433,6 @@ class LInfFMNAttack(FMNAttackLp):
         binary_search_steps: Number of steps to use for the search
             from the adversarial points. If no initial attack or adversarial
             starting point is provided, this parameter will be ignored.
-
-    References:
-        .. [#Pintor21Linf] Maura Pintor, Fabio Roli, Wieland Brendel,
-            Battista Biggio, "Fast Minimum-norm Adversarial
-            Attacks through Adaptive Norm Constraints."
-            arXiv preprint arXiv:2102.12827 (2021).
-            https://arxiv.org/abs/2102.12827
     """
 
     distance = linf
@@ -490,7 +470,7 @@ def mid_points(
 
 
 class L0FMNAttack(FMNAttackLp):
-    """The L0 Fast Minimum Norm adversarial attack, in Lp norm. [#Pintor21L0]_
+    """The L0 Fast Minimum Norm adversarial attack, in Lp norm. [Pintor21]_
 
     Args:
         steps: Number of iterations.
@@ -507,13 +487,6 @@ class L0FMNAttack(FMNAttackLp):
         binary_search_steps: Number of steps to use for the search
             from the adversarial points. If no initial attack or adversarial
             starting point is provided, this parameter will be ignored.
-
-    References:
-        .. [#Pintor21L0] Maura Pintor, Fabio Roli, Wieland Brendel,
-            Battista Biggio, "Fast Minimum-norm Adversarial
-            Attacks through Adaptive Norm Constraints."
-            arXiv preprint arXiv:2102.12827 (2021).
-            https://arxiv.org/abs/2102.12827
     """
 
     distance = l0

diff --git a/foolbox/attacks/mi_fgsm.py b/foolbox/attacks/mi_fgsm.py
@@ -40,7 +40,7 @@ def __call__(self, gradient: ep.Tensor) -> ep.Tensor:
 
 
 class L1MomentumIterativeFastGradientMethod(L1BasicIterativeAttack):
-    """L1 Momentum Iterative Fast Gradient Sign Method (MI-FGSM) [#Dong18]
+    """L1 Momentum Iterative Fast Gradient Sign Method (MI-FGSM) [Dong18]_
 
     Args:
         momentum : Momentum factor for accumulation grad
@@ -74,7 +74,7 @@ def get_optimizer(self, x: ep.Tensor, stepsize: float) -> Optimizer:
 
 
 class L2MomentumIterativeFastGradientMethod(L2BasicIterativeAttack):
-    """L2 Momentum Iterative Fast Gradient Sign Method (MI-FGSM) [#Dong18]
+    """L2 Momentum Iterative Fast Gradient Sign Method (MI-FGSM) [Dong18]_
 
     Args:
         momentum : Momentum factor for accumulation grad
@@ -108,7 +108,7 @@ def get_optimizer(self, x: ep.Tensor, stepsize: float) -> Optimizer:
 
 
 class LinfMomentumIterativeFastGradientMethod(LinfBasicIterativeAttack):
-    """Linf Momentum Iterative Fast Gradient Sign Method (MI-FGSM) [#Dong18]
+    """Linf Momentum Iterative Fast Gradient Sign Method (MI-FGSM) [#Dong18]_
 
     Args:
         momentum : Momentum factor for accumulation grad
@@ -117,9 +117,10 @@ class LinfMomentumIterativeFastGradientMethod(LinfBasicIterativeAttack):
         steps : Number of update steps to perform.
         random_start : Whether the perturbation is initialized randomly or starts at zero.
 
-    References: .. [#Dong18] Dong Y, Liao F, Pang T, et al. Boosting adversarial attacks with momentum[
-    C]//Proceedings of the IEEE conference on computer vision and pattern recognition. 2018: 9185-9193.
-    https://arxiv.org/abs/1710.06081
+    References:
+        .. [#Dong18] Dong Y, Liao F, Pang T, et al. Boosting adversarial attacks with momentum[
+            C]//Proceedings of the IEEE conference on computer vision and pattern recognition. 2018: 9185-9193.
+            https://arxiv.org/abs/1710.06081
     """
 
     def __init__(

diff --git a/foolbox/attacks/virtual_adversarial_attack.py b/foolbox/attacks/virtual_adversarial_attack.py
@@ -17,20 +17,20 @@
 
 
 class VirtualAdversarialAttack(FixedEpsilonAttack):
-    """Second-order gradient-based attack on the logits. [#Miy15]_
+    """Second-order gradient-based attack on the logits. [Miy15]_
     The attack calculate an untargeted adversarial perturbation by performing a
     approximated second order optimization step on the KL divergence between
     the unperturbed predictions and the predictions for the adversarial
     perturbation. This attack was originally introduced as the
-    Virtual Adversarial Training [#Miy15]_ method.
+    Virtual Adversarial Training [Miy15]_ method.
 
     Args:
         steps : Number of update steps.
         xi : L2 distance between original image and first adversarial proposal.
 
 
     References:
-        .. [#Miy15] Takeru Miyato, Shin-ichi Maeda, Masanori Koyama, Ken Nakae,
+        .. [Miy15] Takeru Miyato, Shin-ichi Maeda, Masanori Koyama, Ken Nakae,
             Shin Ishii, "Distributional Smoothing with Virtual Adversarial Training",
             https://arxiv.org/abs/1507.00677
     """