Self host docs

.github/workflows/Documentation.yml

@@ -15,22 +15,39 @@ jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - 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
         run: |
+          git fetch --all
+          # git pull --all
+          # git checkout ${{ github.ref }}
+          git checkout develop
           cd docs
-          make html
+          # make html
+          sphinx-multiversion source build/html
+
+      - name: Make symlinks
+        run: |
+          ln -sf build/html/main stable
+          ln -sf build/html/develop dev
+
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3
-        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        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/
+          publish_dir: docs/build/html/
           # publish_dir: _build/
           # force_orphan: true

.github/workflows/Test.yml

@@ -13,6 +13,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
+        # Test on current Python LTS versions
         python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
         os:
           - ubuntu-latest
@@ -21,10 +22,6 @@ jobs:
         arch:
           - x64
           - x86
-        # exclude:
-        #   # Exclude 32-bit macOS due to Julia support
-        #   - os: macOS-latest
-        #     arch: x86
 
     steps:
       - uses: actions/checkout@v3

README.md

@@ -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

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,7 +14,7 @@
 # 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'
@@ -30,6 +30,7 @@
     'sphinx.ext.autosummary',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
+    "sphinx_multiversion",
     # 'sphinx.ext.autosectionlabel',
     # 'sphinx_autopackagesummary',
 ]
@@ -59,9 +60,54 @@
 
 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

docs/source/index.rst

@@ -10,7 +10,6 @@
 `cvi`: Cluster Validity Indices in Python
 ====================================================
 
-
 These pages serve as the official documentation for the `cvi` Python package, the Python implementation of the `ClusterValidityIndices.jl <https://github.com/AP6YC/ClusterValidityIndices.jl>`_ Julia package.
 
 Cluster Validity Indices (CVIs) tackle the problem of judging the performance of an unsupervised/clustering algorithm without the availability of truth or supervisory labels, resulting in metrics of under- or over-partitioning.

pyproject.toml

@@ -133,6 +133,7 @@ test = [
 docs = [
   "sphinx",
   "furo",
+  "sphinx-multiversion",
 ]
 
 # List URLs that are relevant to your project