Merge pull request #83 from AP6YC/release/v0.6.0

Release/v0.6.0

.github/workflows/Documentation.yml

@@ -0,0 +1,58 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+    tags: '*'
+  pull_request:
+
+# sphinx-build doc _build
+permissions:
+    contents: write
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          lfs: 'true'
+          fetch-depth: 0
+      - uses: actions/setup-python@v3
+
+      - name: Install dependencies
+        run: |
+          # pip install -r docs/requirements.txt
+          pip install -e .[docs]
+
+      - name: Sphinx Build Develop
+        run: |
+          git checkout develop
+          git fetch --all
+          git pull --all
+          cd ${{ github.workspace }}/docs
+          # make html
+          sphinx-multiversion source build/html
+
+      - name: Sphinx Build Main
+        run: |
+          git checkout main
+          cd ${{ github.workspace }}/docs
+          sphinx-multiversion source build/html
+
+      - name: Make symlinks
+        run: |
+          ln -sf build/html/main build/html/stable
+          ln -sf build/html/develop build/html/dev
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' && ((github.ref == 'refs/heads/main') || (github.ref == 'refs/heads/develop'))}}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # publish_dir: docs/build/
+          publish_dir: docs/build/html/
+          # publish_dir: _build/
+          # force_orphan: true

.github/workflows/Test.yml

@@ -13,18 +13,15 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        # Test on current Python LTS versions
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
         os:
           - ubuntu-latest
-          - macOS-latest
+          # - macOS-latest
           # - windows-latest
         arch:
           - x64
           - x86
-        exclude:
-          # Exclude 32-bit macOS due to Julia support
-          - os: macOS-latest
-            arch: x86
 
     steps:
       - uses: actions/checkout@v3
@@ -35,8 +32,9 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install flake8 pytest
-          pip install -r requirements.txt
+          # pip install flake8 pytest
+          # pip install -r requirements.txt
+          pip install -e .[test]
       # if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
       - name: Lint with flake8
         run: |

.gitignore

@@ -1,10 +1,18 @@
+# -----------------------------------------------------------------------------
+# PROJECT IGNORES
+# -----------------------------------------------------------------------------
+
 # IDE ignores
 .vscode/
 
 # Project ignores
 _dev/
 **/_autosummary/
 
+# -----------------------------------------------------------------------------
+# PYTHON IGNORES
+# -----------------------------------------------------------------------------
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

README.md

@@ -1,4 +1,4 @@
-# cvi
+[![cvi-header](https://github.com/AP6YC/FileStorage/blob/main/cvi/header.png?raw=true)][docs-dev-url]
 
 A Python package implementing both batch and incremental cluster validity indices (CVIs).
 
@@ -14,11 +14,11 @@ A Python package implementing both batch and incremental cluster validity indice
 [zenodo-img]: https://zenodo.org/badge/526280198.svg
 [zenodo-url]: https://zenodo.org/badge/latestdoi/526280198
 
-[docs-stable-img]: https://readthedocs.org/projects/cluster-validity-indices/badge/?version=latest
-[docs-stable-url]: https://cluster-validity-indices.readthedocs.io/en/latest/?badge=latest
+[docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg
+[docs-stable-url]: https://AP6YC.github.io/cvi/stable
 
-[docs-dev-img]: https://readthedocs.org/projects/cluster-validity-indices/badge/?version=develop
-[docs-dev-url]: https://cluster-validity-indices.readthedocs.io/en/develop/?badge=develop
+[docs-dev-img]: https://img.shields.io/badge/docs-dev-blue.svg
+[docs-dev-url]: https://AP6YC.github.io/cvi/dev
 
 [ci-img]: https://github.com/AP6YC/cvi/actions/workflows/Test.yml/badge.svg
 [ci-url]: https://github.com/AP6YC/cvi/actions/workflows/Test.yml
@@ -34,19 +34,21 @@ A Python package implementing both batch and incremental cluster validity indice
 
 ## Table of Contents
 
-- [cvi](#cvi)
-  - [Table of Contents](#table-of-contents)
-  - [Cluster Validity Indices](#cluster-validity-indices)
-  - [Installation](#installation)
-  - [Usage](#usage)
-    - [Quickstart](#quickstart)
-    - [Detailed Usage](#detailed-usage)
-  - [Implemented CVIs](#implemented-cvis)
-  - [History](#history)
-  - [Acknowledgements](#acknowledgements)
-    - [Derivation](#derivation)
-    - [Authors](#authors)
-    - [Related Projects](#related-projects)
+- [Table of Contents](#table-of-contents)
+- [Cluster Validity Indices](#cluster-validity-indices)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Quickstart](#quickstart)
+  - [Detailed Usage](#detailed-usage)
+- [Implemented CVIs](#implemented-cvis)
+- [History](#history)
+- [Acknowledgements](#acknowledgements)
+  - [Derivation](#derivation)
+  - [Authors](#authors)
+  - [Related Projects](#related-projects)
+  - [Assets](#assets)
+    - [Fonts](#fonts)
+    - [Icons](#icons)
 
 ## Cluster Validity Indices
 
@@ -77,7 +79,7 @@ pip install cvi
 You can also specify a version to install in the usual way with
 
 ```python
-pip install cvi==v0.5.1
+pip install cvi==v0.6.0
 ```
 
 Alternatively, you can manually install a release from the [releases page](https://github.com/AP6YC/cvi/releases) on GitHub.
@@ -141,7 +143,7 @@ samples, labels = my_clustering_alg(some_data)
 > **NOTE**:
 >
 > The `cvi` package assumes the Numpy **row-major** convention where rows are individual samples and columns are features.
-> A batch dataset is then `[n_samples, n_features]` large, and their corresponding labels are '[n_samples]` large.
+> A batch dataset is then `[n_samples, n_features]` large, and their corresponding labels are `[n_samples]` large.
 
 You may compute the final criterion value with a batch update all at once with `CVI.get_cvi`
 
@@ -187,12 +189,14 @@ The following CVIs have been implemented as of the latest version of `cvi`:
 
 - 8/18/2022: Initialize project.
 - 9/8/2022: First release on PyPi and initiate GitFlow.
+- 8/10/2023: v0.5.1 released.
+- 5/31/2024: Updated documentation.
 
 ## Acknowledgements
 
 ### Derivation
 
-The incremental and batch CVI implementations in this package are largely derived from the following Julia language implementations:
+The incremental and batch CVI implementations in this package are largely derived from the following Julia language implementations by the same authors of this package:
 
 - [ClusterValidityIndices.jl](https://github.com/AP6YC/ClusterValidityIndices.jl)
 
@@ -209,3 +213,17 @@ If this package is missing something that you need, feel free to check out some
 
 - [validclust](https://github.com/crew102/validclust)
 - [clusterval](https://github.com/Nuno09/clusterval)
+
+### Assets
+
+#### Fonts
+
+The following font is used in the logo:
+
+- [Ethnocentric Font Family](https://www.1001fonts.com/ethnocentric-font.html)
+
+#### Icons
+
+The icon for the project is taken from:
+
+- [Cluster computing icons created by IconBaandar - Flaticon](https://www.flaticon.com/free-icons/cluster-computing) ([cluster-5464694](https://www.flaticon.com/free-icon/cluster_5464694))

docs/Makefile

@@ -4,7 +4,8 @@
 # You can set these variables from the command line, and also
 # from the environment for the first two.
 SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
+# SPHINXBUILD   ?= sphinx-build
+SPHINXBUILD   ?= sphinx-multiversion
 SOURCEDIR     = source
 BUILDDIR      = build
 

docs/make.bat

@@ -5,7 +5,8 @@ pushd %~dp0
 REM Command file for Sphinx documentation
 
 if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
+	@REM set SPHINXBUILD=sphinx-build
+	set SPHINXBUILD=sphinx-multiversion
 )
 set SOURCEDIR=source
 set BUILDDIR=build

docs/source/_templates/page.html

@@ -0,0 +1,17 @@
+{% extends "!page.html" %}
+{% block body %}
+{% if current_version and latest_version and current_version != latest_version %}
+<p>
+  <strong>
+    {% if current_version.is_released %}
+    You're reading an old version of this documentation.
+    If you want up-to-date information, please have a look at <a href="{{ vpathto(latest_version.name) }}">{{latest_version.name}}</a>.
+    {% else %}
+    You're reading the documentation for a development version.
+    For the latest released version, please have a look at <a href="{{ vpathto(latest_version.name) }}">{{latest_version.name}}</a>.
+    {% endif %}
+  </strong>
+</p>
+{% endif %}
+{{ super() }}
+{% endblock %}%

docs/source/_templates/versioning.html

@@ -0,0 +1,12 @@
+{% if versions %}
+<div class="sidebar-tree">
+  <p class="caption" role="heading">
+    <span class="caption-text">{{ _('Docs Versions') }}</span>
+  </p>
+  <ul class="current">
+    {%- for item in versions %}
+    <li class="toctree-l1"><a class="reference internal" href="{{ item.url }}">{{ item.name }}</a></li>
+    {%- endfor %}
+  </ul>
+</div>
+{% endif %}

docs/source/conf.py

@@ -14,10 +14,10 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'cvi'
-copyright = '2022, Sasha Petrenko'
+copyright = '2024, Sasha Petrenko'
 author = 'Sasha Petrenko'
-release = '0.5.1'
-version = '0.5.1'
+release = '0.6.0'
+version = '0.6.0'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -30,6 +30,7 @@
     'sphinx.ext.autosummary',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
+    "sphinx_multiversion",
     # 'sphinx.ext.autosectionlabel',
     # 'sphinx_autopackagesummary',
 ]
@@ -54,13 +55,59 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 # html_theme = 'alabaster'
-html_theme = 'sphinx_rtd_theme'
+# html_theme = 'sphinx_rtd_theme'
+html_theme = 'furo'
 
 html_static_path = ['_static']
 
+html_sidebars = {
+    "**": [
+        "sidebar/scroll-start.html",
+        "sidebar/brand.html",
+        "sidebar/search.html",
+        "sidebar/navigation.html",
+        "sidebar/ethical-ads.html",
+        "sidebar/scroll-end.html",
+        "versioning.html",
+    ],
+}
+
+# html_css_files = [
+#     'css/rtd.css',
+# ]
+
 # -- Options for EPUB output
 epub_show_urls = 'footnote'
 
+
+# Whitelist pattern for tags (set to None to ignore all tags)
+# smv_tag_whitelist = r'^.*$'
+# smv_tag_whitelist = r'v*'
+smv_tag_whitelist = None
+# smv_tag_pattern = r'^v\d*\.\d*\.\d*$'
+# smv_tag_pattern = r'^.*(?!alpha)$'
+
+# Whitelist pattern for branches (set to None to ignore all branches)
+# smv_branch_whitelist = r'^.*$
+# smv_branch_whitelist = None
+# smv_branch_whitelist = r'^(main|develop)$'
+# smv_branch_whitelist = r'^self-host-docs$'
+smv_branch_whitelist = r'^(main|develop)$'
+
+# Whitelist pattern for remotes (set to None to use local branches only)
+smv_remote_whitelist = None
+
+# Pattern for released versions
+# smv_released_pattern = r'^v.*$'
+# smv_released_pattern = r'v\d*\.\d*\.\d*'
+smv_released_pattern = r'^tags/.*$'
+
+# Format for versioned output directories inside the build directory
+smv_outputdir_format = '{ref.name}'
+
+# Determines whether remote or local git branches/tags are preferred if their output dirs conflict
+smv_prefer_remote_refs = False
+
 # # Skip param objects because of their weird rendering in docs
 # def maybe_skip_member(app, what, name, obj, skip, options):
 #     # print app, what, name, obj, skip, options