NorskRegnesentral · Tveten · Oct 16, 2024 · Oct 6, 2024 · Oct 6, 2024 · Oct 6, 2024
diff --git a/.gitignore b/.gitignore
@@ -159,6 +159,11 @@ cython_debug/
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
 
+# VS Code settings
 .vscode/
 
+# Ruff
 .ruff_cache/
+
+# Sphinx documentation
+docs/source/api_reference/auto_generated/
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -12,7 +12,7 @@ python:
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "3.12"
 
 sphinx:
   configuration: docs/source/conf.py

diff --git a/README.md b/README.md
@@ -1,13 +1,18 @@
-# skchange
-`skchange` provides sktime-compatible change detection and changepoint-based anomaly detection algorithms.
-
-A playground for now.
+# [skchange](https://skchange.readthedocs.io/en/latest/)
 
 [![codecov](https://codecov.io/gh/NorskRegnesentral/skchange/graph/badge.svg?token=QSS3AY45KY)](https://codecov.io/gh/NorskRegnesentral/skchange)
 [![tests](https://github.com/NorskRegnesentral/skchange/actions/workflows/tests.yaml/badge.svg)](https://github.com/NorskRegnesentral/skchange/actions/workflows/tests.yaml)
+[![docs](https://readthedocs.org/projects/skchange/badge/?version=latest)](https://skchange.readthedocs.io/en/latest/?badge=latest)
 [![BSD 3-clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://github.com/sktime/sktime/blob/main/LICENSE)
 [![!black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
+Skchange provides sktime-compatible change detection and changepoint-based anomaly detection algorithms.
+
+Experimental but maturing.
+
+## [Documentation](https://skchange.readthedocs.io/en/latest/)
+Now available.
+
 
 ## Installation
 ```sh
@@ -20,9 +25,9 @@ Requires Python >= 3.9, < 3.13.
 ### Changepoint detection / time series segmentation
 ```python
 from skchange.change_detectors.moscore import Moscore
-from skchange.datasets.generate import generate_teeth_data
+from skchange.datasets.generate import generate_alternating_data
 
-df = generate_teeth_data(n_segments=10, segment_length=50, mean=5, random_state=1)
+df = generate_alternating_data(n_segments=10, segment_length=50, mean=5, random_state=1)
 detector = Moscore(bandwidth=10)
 detector.fit_predict(df)
 >>>
@@ -41,9 +46,9 @@ Name: changepoint, dtype: int64
 ### Multivariate anomaly detection
 ```python
 from skchange.anomaly_detectors.mvcapa import Mvcapa
-from skchange.datasets.generate import generate_teeth_data
+from skchange.datasets.generate import generate_alternating_data
 
-df = generate_teeth_data(
+df = generate_alternating_data(
     n_segments=5,
     segment_length=50,
     p=10,

diff --git a/build_tools/make_release.py b/build_tools/make_release.py
@@ -29,9 +29,9 @@ class URLs:
     """Container class for URLs."""
 
     DOCS_LOCAL = "file://" + os.path.realpath(
-        os.path.join(ROOT_DIR, "docs/_build/html/index.html")
+        os.path.join(ROOT_DIR, "docs/build/html/index.html")
     )
-    DOCS_ONLINE = "https://www.sktime.net"
+    DOCS_ONLINE = "https://skchange.readthedocs.io/"
     PYPI = f"https://pypi.org/simple/{PACKAGE_NAME}/"
 
 
@@ -337,8 +337,8 @@ def main():
         CheckVersionNumber(),
         UpdateReadme(),
         # UpdateChangelog(),
-        # MakeDocs(),
-        # CheckLocalDocs(),
+        MakeDocs(),
+        CheckLocalDocs(),
         MakeDist(),
         CheckDist(),
         UploadToTestPyPI(),
@@ -349,7 +349,7 @@ def main():
         GitTagRelease(),
         PushTagToGitHub(),
         CheckCIStatus(),
-        # CheckOnlineDocs(),
+        CheckOnlineDocs(),
         UploadToPyPI(),
         CheckPyPIFiles(),
     ]

diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,34 @@
+# Adapted from sktime docs/Makefile.
+
+# Minimal makefile for Sphinx documentation.
+
+# You can set these variables from the command line.
+SPHINXBUILD        = sphinx-build
+SPHINXOPTS         =
+SPHINXAUTOBUILD    = sphinx-autobuild
+SPHINXAUTOOPTS     =
+SOURCEDIR          = ./source
+BUILDDIR           = ./build
+SKCHANGEDIR        = ../skchange
+
+.PHONY: help build autobuild
+
+# "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)"
+
+clean:
+	rm -rf $(BUILDDIR)
+	@echo "Deleted directory $(BUILDDIR)."
+
+# $(O) is meant as a shortcut for custom options.
+# i.e to log stderr into a separate file:
+# make build O="--no-color 2> build_warnings.log"
+html:
+#	./symlink_examples.sh
+	$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# $(O) is meant as a shortcut for custom options.
+autobuild:
+#   use --pre-build COMMAND to call ./symlink_examples.sh
+	$(SPHINXAUTOBUILD) "$(SOURCEDIR)" "$(BUILDDIR)/html" -d "$(BUILDDIR)/doctrees" $(SPHINXAUTOOPTS) $(O) --watch "$(SKCHANGEDIR)" --re-ignore ".*\.json"
diff --git a/docs/source/_templates/class.rst b/docs/source/_templates/class.rst
@@ -0,0 +1,12 @@
+{{objname}}
+{{ underline }}==============
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+.. include:: {{module}}.{{objname}}.examples
+
+.. raw:: html
+
+    <div class="clearer"></div>
diff --git a/docs/source/_templates/functions.rst b/docs/source/_templates/functions.rst
@@ -0,0 +1,12 @@
+{{objname}}
+{{ underline }}====================
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}
+
+.. include:: {{module}}.{{objname}}.examples
+
+.. raw:: html
+
+    <div class="clearer"></div>
diff --git a/docs/source/api_reference.rst b/docs/source/api_reference.rst
@@ -0,0 +1,25 @@
+.. _api_reference:
+
+=============
+API reference
+=============
+
+Welcome to the API reference for ``skchange``.
+
+The API reference provides a technical manual.
+It describes the classes and functions included in skchange.
+
+For Python Interactive examples, see the `interactive <https://github.com/NorskRegnesentral/skchange/tree/main/interactive>`_ folder on Github.
+
+.. include:: includes/api_css.rst
+
+.. toctree::
+   :maxdepth: 1
+
+   api_reference/base
+   api_reference/anomaly_detectors
+   api_reference/change_detectors
+   api_reference/scores
+   api_reference/costs
+   api_reference/datasets
+   api_reference/utils
diff --git a/docs/source/api_reference/anomaly_detectors.rst b/docs/source/api_reference/anomaly_detectors.rst
@@ -0,0 +1,40 @@
+.. _anomaly_detectors:
+
+Anomaly detectors
+=================
+
+
+Base
+----
+
+.. currentmodule:: skchange.anomaly_detectors
+.. autosummary::
+    :toctree: auto_generated/
+    :template: class.rst
+
+    CollectiveAnomalyDetector
+    SubsetCollectiveAnomalyDetector
+    PointAnomalyDetector
+
+Collective anomaly detectors
+----------------------------
+.. currentmodule:: skchange.anomaly_detectors
+
+.. autosummary::
+    :toctree: auto_generated/
+    :template: class.rst
+
+    Capa
+    CircularBinarySegmentation
+    MoscoreAnomaly
+    StatThresholdAnomaliser
+
+Subset collective anomaly detectors
+-----------------------------
+.. currentmodule:: skchange.anomaly_detectors
+
+.. autosummary::
+    :toctree: auto_generated/
+    :template: class.rst
+
+    Mvcapa
diff --git a/docs/source/api_reference/base.rst b/docs/source/api_reference/base.rst
@@ -0,0 +1,25 @@
+.. _base:
+
+Base
+====
+
+The :mod:`skchange.base` module contains the abstract detector class
+:class:`skchange.base.BaseDetector`. This class serves as a minimalistic template for
+all the detectors in :mod:`skchange`.
+
+For common detection tasks, like changepoint detection or anomaly detection, there
+are dedicated subclasses of :class:`BaseDetector` that implement a stricter template
+for these tasks. These subclasses are located in the respective modules, e.g.
+:mod:`skchange.change_detectors.base` or :mod:`skchange.anomaly_detectors.base`.
+
+
+Base classes
+------------
+
+.. currentmodule:: skchange.base
+
+.. autosummary::
+    :toctree: auto_generated/
+    :template: class.rst
+
+    BaseDetector
diff --git a/docs/source/api_reference/change_detectors.rst b/docs/source/api_reference/change_detectors.rst
@@ -0,0 +1,27 @@
+.. _change_detectors:
+
+Change detectors
+================
+
+Base
+----
+
+.. currentmodule:: skchange.change_detectors
+
+.. autosummary::
+   :toctree: auto_generated/
+   :template: class.rst
+
+   ChangeDetector
+
+Change detectors
+----------------
+.. currentmodule:: skchange.change_detectors
+
+.. autosummary::
+   :toctree: auto_generated/
+   :template: class.rst
+
+   Moscore
+   Pelt
+   SeededBinarySegmentation
diff --git a/docs/source/api_reference/costs.rst b/docs/source/api_reference/costs.rst
@@ -0,0 +1,28 @@
+.. _costs:
+
+Costs and savings
+=================
+
+Costs
+-----
+
+.. currentmodule:: skchange.costs
+
+.. autosummary::
+    :toctree: auto_generated/
+    :template: functions.rst
+
+    cost_factory
+    init_mean_cost
+    mean_cost
+
+Savings
+-------
+
+.. autosummary::
+    :toctree: auto_generated/
+    :template: functions.rst
+
+    saving_factory
+    init_mean_saving
+    mean_saving
diff --git a/docs/source/api_reference/datasets.rst b/docs/source/api_reference/datasets.rst
@@ -0,0 +1,15 @@
+.. _datasets:
+
+Datasets
+========
+
+.. currentmodule:: skchange.datasets
+
+.. autosummary::
+    :toctree: auto_generated/
+    :template: functions.rst
+
+    generate_anomalous_data
+    generate_changing_data
+    generate_alternating_data
+    add_linspace_outliers
diff --git a/docs/source/api_reference/scores.rst b/docs/source/api_reference/scores.rst
@@ -0,0 +1,21 @@
+.. _scores:
+
+Scores
+======
+
+.. currentmodule:: skchange.scores
+
+.. autosummary::
+    :toctree: auto_generated/
+    :template: functions.rst
+
+    score_factory
+    anomaly_score_factory
+    init_mean_score
+    mean_score
+    mean_anomaly_score
+    init_mean_var_score
+    mean_var_score
+    mean_var_anomaly_score
+    init_mean_cov_score
+    mean_cov_score
diff --git a/docs/source/api_reference/utils.rst b/docs/source/api_reference/utils.rst
@@ -0,0 +1,26 @@
+.. _utils:
+
+Utility functions
+=================
+
+Data validation
+---------------
+.. currentmodule:: skchange.utils.validation.data
+
+.. autosummary::
+    :toctree: auto_generated/
+    :template: functions.rst
+
+    check_data
+
+Parameter validation
+--------------------
+.. currentmodule:: skchange.utils.validation.parameters
+
+.. autosummary::
+    :toctree: auto_generated/
+    :template: functions.rst
+
+    check_larger_than
+    check_smaller_than
+    check_in_interval