Merge pull request #1429 from HaoZeke/cleanDocs

MAINT: Clean and update documentation

.gitignore

@@ -1,3 +1,6 @@
+# Added
+/docs/html/
+docs/source/autoapi/
 # Compiled files
 *.py[cod]
 *.a
@@ -46,4 +49,3 @@ htmlcov
 
 # Mac OSX
 .DS_Store
-/docs/html/

asv/__init__.py

@@ -1,6 +1,9 @@
 # Licensed under a 3-clause BSD style license - see LICENSE.rst
 
-from asv._version import version as __version__
+from importlib_metadata import version as get_version
+
 from asv import plugin_manager  # noqa F401 Needed to load the plugins
 
+__version__ = get_version("asv")
+
 __all__ = '__version__',

asv/statistics.py → asv/_stats.py

@@ -76,8 +76,9 @@ def mann_whitney_u(x, y, method='auto'):
     """
     Mann-Whitney U test
 
-    Ties are handled conservatively, returning the least significant
-    tie breaking.
+    Ties are handled conservatively, returning the least significant tie
+    breaking.
+    :cite:empty:`mwu-mannTestWhetherOne1947,mwu-gibbonsNonparametricStatisticalInference2010`.
 
     Parameters
     ----------
@@ -96,8 +97,10 @@ def mann_whitney_u(x, y, method='auto'):
 
     References
     ----------
-    .. [1] Mann & Whitney, Ann. Math. Statist. 18, 50 (1947).
-    .. [2] Gibbons & Chakraborti, "Nonparametric statistical inference". (2003)
+    .. bibliography::
+       :filter: docname in docnames
+       :labelprefix: MWU_
+       :keyprefix: mwu-
 
     """
     memo = _mann_whitney_u_memo
@@ -177,11 +180,19 @@ def mann_whitney_u_r(m, n, u, memo=None):
     Number of orderings in Mann-Whitney U test.
 
     The PMF of U for samples of sizes (m, n) is given by
-    p(u) = r(m, n, u) / binom(m + n, m).
+    :cite:empty:`mwur-mannTestWhetherOne1947`
+
+    .. code-block::
+
+       p(u) = r(m, n, u) / binom(m + n, m).
 
     References
     ----------
-    .. [1] Mann & Whitney, Ann. Math. Statist. 18, 50 (1947).
+    .. bibliography::
+       :filter: docname in docnames
+       :labelprefix: MWUR_
+       :keyprefix: mwur-
+
     """
     if u < 0:
         value = 0

asv/commands/__init__.py

@@ -14,7 +14,6 @@
     'Machine',
     'Setup',
     'Run',
-    'Dev',
     'Continuous',
     'Find',
     'Rm',

asv/commands/common_args.py

@@ -5,7 +5,9 @@
 import multiprocessing
 import argparse
 
-from .. import __version__, util
+from importlib_metadata import version as get_version
+
+from asv import util
 
 
 def add_global_arguments(parser, suppress_defaults=True):
@@ -29,7 +31,8 @@ def add_global_arguments(parser, suppress_defaults=True):
         default=(argparse.SUPPRESS if suppress_defaults else None))
 
     parser.add_argument(
-        "--version", action="version", version="%(prog)s " + __version__,
+        "--version", action="version",
+        version="%(prog)s " + get_version("asv"),
         help="Print program version",
         **suppressor)
 

asv/commands/compare.py

@@ -15,7 +15,7 @@
 from ..util import human_value, load_json
 from ..console import log
 from ..environment import get_environments
-from .. import util, statistics
+from .. import util, _stats
 
 
 def mean(values):
@@ -76,7 +76,7 @@ def _is_result_better(a, b, a_ss, b_ss, factor, use_stats=True):
         # Special-case the situation with only one sample, in which
         # case we do the comparison only based on `factor` as there's
         # not enough data to do statistics.
-        if not statistics.is_different(a_ss[1], b_ss[1],
+        if not _stats.is_different(a_ss[1], b_ss[1],
                                        a_ss[0], b_ss[0]):
             return False
 

asv/commands/publish.py

@@ -5,15 +5,17 @@
 import datetime
 from collections import defaultdict
 
-from . import Command
-from ..benchmarks import Benchmarks
-from ..console import log
-from ..graph import GraphSet
-from ..machine import iter_machine_files
-from ..repo import get_repo
-from ..results import iter_results
-from ..publishing import OutputPublisher
-from .. import statistics, util, __version__
+from importlib_metadata import version as get_version
+
+from asv.commands import Command
+from asv.benchmarks import Benchmarks
+from asv.console import log
+from asv.graph import GraphSet
+from asv.machine import iter_machine_files
+from asv.repo import get_repo
+from asv.results import iter_results
+from asv.publishing import OutputPublisher
+from asv import _stats, util
 
 
 def check_benchmark_params(name, benchmark):
@@ -189,7 +191,7 @@ def copy_ignore(src, names):
                     b_params = b['params']
 
                     result = results.get_result_value(key, b_params)
-                    weight = [statistics.get_weight(s)
+                    weight = [_stats.get_weight(s)
                               for s in results.get_result_stats(key, b_params)]
                     if not b_params:
                         result = result[0]
@@ -281,7 +283,7 @@ def copy_ignore(src, names):
         }, compact=True)
 
         util.write_json(os.path.join(conf.html_dir, "info.json"), {
-            'asv-version': __version__,
+            'asv-version': get_version("asv"),
             'timestamp': util.datetime_to_js_timestamp(
                 datetime.datetime.now(datetime.timezone.utc)
             )

asv/commands/rm.py

@@ -4,7 +4,9 @@
 
 from asv_runner.console import get_answer_default
 
-from . import Command, util
+from asv import util
+
+from . import Command
 from ..console import log
 from ..results import iter_results
 

asv/graph.py

@@ -16,7 +16,7 @@
 
 
 class GraphSet:
-    """Manage multiple `Graph`"""
+    """Manage multiple :py:class:`Graph` objects"""
 
     def __init__(self):
         self._graphs = {}
@@ -326,15 +326,19 @@ def make_summary_graph(graphs):
 
 def _compute_summary_data_series(*ys):
     """
-    Given multiple input series::
+    Given a multiple input series:
 
-        y0, y1, ...
+    .. code-block::
 
-    calculate summary data series::
+           y0, y1, ...
 
-        val = [geom_mean([y0[0], y1[0], ...]),
-               geom_mean([y0[1], y1[1], ...]),
-               ...]
+    calculate summary data series:
+
+    .. code-block::
+
+           val = [geom_mean([y0[0], y1[0], ...]),
+                  geom_mean([y0[1], y1[1], ...]),
+                 ...]
 
     Missing data in each y-series is filled for each series
     separately, before averaging. Data points that are missing from

asv/plugin_manager.py

@@ -12,8 +12,8 @@ class PluginManager:
     """
     A class to load and manage plugins.
 
-    By default in asv, plugins are searched for in the `asv.plugins`
-    namespace package and in the `asv.commands` package.
+    By default in asv, plugins are searched for in the :py:mod:`asv.plugins`
+    namespace package and in the :py:mod:`asv.commands` package.
 
     Then, any modules specified in the ``plugins`` entry in the
     ``asv.conf.json`` file are loaded.

asv/plugins/_mamba_helpers.py

@@ -218,18 +218,24 @@ def replace_channels(self):
 
     def solve(self, specs, pkg_cache_path=None):
         """Solve given a set of specs.
+
         Parameters
         ----------
+
         specs : list of str
-            A list of package specs. You can use `conda.models.match_spec.MatchSpec`
-            to get them to the right form by calling
-            `MatchSpec(mypec).conda_build_form()`
+            A list of package specs. You can use
+            ``conda.models.match_spec.MatchSpec`` to get them to the right form
+            by calling ``MatchSpec(mypec).conda_build_form()``
+
         Returns
         -------
+
         transaction : libmambapy.Transaction
             The mamba transaction.
+
         Raises
         ------
+
         RuntimeError :
             If the solver did not find a solution.
         """

asv/plugins/mamba.py

@@ -12,7 +12,9 @@
 except ImportError:
     from yaml import Loader
 
-from ._mamba_helpers import libmambapy, MambaSolver
+import libmambapy
+
+from ._mamba_helpers import MambaSolver
 from .. import environment, util
 from ..console import log