Improve docs

alns/accept/RecordToRecordTravel.py

@@ -10,22 +10,30 @@ class RecordToRecordTravel(AcceptanceCriterion):
     """
     The Record-to-Record Travel (RRT) criterion accepts a candidate solution
     if the absolute gap between the candidate and the best or current solution
-    is smaller than a threshold. The threshold is updated in each iteration as:
+    is smaller than a threshold. The threshold :math:`T` is updated in each
+    iteration as:
 
-    ``threshold = max(end_threshold, threshold - step)`` (linear)
+    .. math::
 
-    ``threshold = max(end_threshold, step * threshold)`` (exponential)
+        T \\gets \\max \\{ T_\\text{end},~T - \\gamma \\}
 
-    where the initial threshold is set to ``start_threshold``.
+    when ``method = 'linear'``, or
+
+    .. math::
+
+        T \\gets \\max \\{ T_\\text{end},~\\gamma T \\}
+
+    when ``method = 'exponential'``. Initially, :math:`T` is set to
+    :math:`T_\\text{start}`.
 
     Parameters
     ----------
     start_threshold
-        The initial threshold.
+        The initial threshold :math:`T_\\text{start} \\ge 0`.
     end_threshold
-        The final threshold.
+        The final threshold :math:`T_\\text{end} \\ge 0`.
     step
-        The updating step.
+        The updating step :math:`\\gamma \\ge 0`.
     method
         The updating method, one of {'linear', 'exponential'}. Default
         'linear'.

alns/accept/SimulatedAnnealing.py

@@ -10,23 +10,30 @@
 
 class SimulatedAnnealing(AcceptanceCriterion):
     """
-    Simulated annealing, using an updating temperature. The temperature is
-    updated as,
+    Simulated annealing, using an updating temperature. The current temperature
+    :math:`T` is updated as
 
-    ``temperature = max(end_temperature, temperature - step)`` (linear)
+    .. math::
 
-    ``temperature = max(end_temperature, step * temperature)`` (exponential)
+        T \\gets \\max \\{ T_\\text{end},~T - \\gamma \\}
 
-    where the initial temperature is set to ``start_temperature``.
+    when ``method = 'linear'``, or
+
+    .. math::
+
+        T \\gets \\max \\{ T_\\text{end},~\\gamma T \\}
+
+    when ``method = 'exponential'``. Initially, :math:`T` is set to
+    :math:`T_\\text{start}`.
 
     Parameters
     ----------
     start_temperature
-        The initial temperature.
+        The initial temperature :math:`T_\\text{start} > 0`.
     end_temperature
-        The final temperature.
+        The final temperature :math:`T_\\text{end} > 0`.
     step
-        The updating step.
+        The updating step :math:`\\gamma \\ge 0`.
     method
         The updating method, one of {'linear', 'exponential'}. Default
         'exponential'.

alns/accept/WorseAccept.py

@@ -4,28 +4,34 @@
 
 class WorseAccept(AcceptanceCriterion):
     """
-    The Worse Accept criterion accepts a candidate solution 1) if it improves
-    over the current one or 2) with a given probability regardless of the cost.
-    The probability is updated in each iteration as:
+    The Worse Accept criterion accepts a candidate solution if it improves over
+    the current one, or with a given probability :math:`P` regardless of the
+    cost. :math:`P` is updated in each iteration as:
 
-    ``prob = max(end_prob, prob - step)`` (linear)
+    .. math::
 
-    ``prob = max(end_prob, step * prob)`` (exponential)
+        P \\gets \\max \\{ P_\\text{end},~P - \\gamma \\}
 
-    where the initial probability is set to ``start_prob``.
+    when ``method = 'linear'``, or
+
+    .. math::
+
+        P \\gets \\max \\{ P_\\text{end},~\\gamma P \\}
+
+    when ``method = 'exponential'``. Initially, :math:`P` is set to
+    :math:`P_\\text{start}`.
 
     Parameters
     ----------
     start_prob
-        The initial probability.
+        The initial probability :math:`P_\\text{start} \\in [0, 1]`.
     end_prob
-        The final probability.
+        The final probability :math:`P_\\text{end} \\in [0, 1]`.
     step:
-        The updating step.
+        The updating step :math:`\\gamma \\ge 0`.
     method
         The updating method, one of {'linear', 'exponential'}. Default
         'linear'.
-
     """
 
     def __init__(

docs/source/conf.py

@@ -35,6 +35,26 @@
 
 nbsphinx_execute = "never"
 
+nbsphinx_prolog = r"""
+{% set docname = 'docs/source/' + env.doc2path(env.docname, base=None) %}
+{% set url_prefix = 'https://github.com/N-Wouda/ALNS/blob/' %}
+{% set release = env.config.release %}
+
+.. raw:: html
+
+   <div class="admonition note">
+     <p class="admonition-title">
+        Note
+     </p>
+     <p>
+        This page was generated from
+        <a class="reference external"
+           href="{{ url_prefix|e }}v{{ release|e }}/{{ docname|e }}">
+           {{ docname|e }}</a>.
+     </p>
+   </div>
+"""
+
 # -- General configuration
 
 extensions = [

docs/source/index.rst

@@ -20,13 +20,13 @@ The documentation hosted on this site provides several examples of how the ALNS
    examples/travelling_salesman_problem
    examples/capacitated_vehicle_routing_problem
    examples/permutation_flow_shop_problem
-   other single-trajectory heuristics
+   examples/other single-trajectory heuristics
 
 .. toctree::
    :maxdepth: 1
    :caption: API reference
 
-   alns
-   accept
-   select
-   stop
+   api/alns
+   api/accept
+   api/select
+   api/stop