DOC - Enable viewing dev and stable versions of package documentation (#206)

Author: Badr-MOUFAD

.circleci/config.yml

@@ -78,9 +78,21 @@ jobs:
                 chmod og= ~/.ssh/config
                 cd doc;
                 pip install ghp-import;
+                make add-stable-doc
                 make install
               fi
 
+        # Add stable documentation
+        - run:
+            name: stable_doc
+            command: |
+              set -e
+              mkdir -p ~/.ssh
+              echo -e "Host *\nStrictHostKeyChecking no" > ~/.ssh/config
+              chmod og= ~/.ssh/config
+              cd doc;
+              make add-stable-doc
+
         # Save the outputs
         - store_artifacts:
             path: doc/_build/html/

doc/Makefile

@@ -9,6 +9,7 @@ BUILDDIR      = _build
 
 GITHUB_PAGES_BRANCH = gh-pages
 OUTPUTDIR = _build/html
+STABLE_DOC_DIR = stable
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
@@ -138,3 +139,14 @@ install:
 	touch $(OUTPUTDIR)/.nojekyll
 	ghp-import -m "Generate Pelican site [ci skip]" -b $(GITHUB_PAGES_BRANCH) $(OUTPUTDIR)
 	git push origin $(GITHUB_PAGES_BRANCH)
+
+.PHONY: add-stable-doc
+add-stable-doc:
+# switch to GITHUB_PAGES_BRANCH where stable build is located
+	git fetch origin $(GITHUB_PAGES_BRANCH)
+	git checkout $(GITHUB_PAGES_BRANCH)
+	git pull origin $(GITHUB_PAGES_BRANCH)
+# move the content of the stable build to the output dir
+	mv ../$(STABLE_DOC_DIR) $(OUTPUTDIR)
+# switch back to main and get to doc directory
+	git checkout main

doc/_static/style.css

@@ -0,0 +1,24 @@
+.announcement {
+    background-color: #1f77b4;
+}
+
+.sidebar-version {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    justify-content: space-between;
+
+    padding-left: var(--sidebar-item-spacing-horizontal);
+    padding-right: var(--sidebar-item-spacing-horizontal);
+    margin-top: 0px;
+}
+
+.sidebar-version-selected>* {
+    display: flex;
+    align-items: center;
+    padding: 0.25em;
+    border-radius: 0.25rem;
+    background-color: #ff7f0e;
+    color: white;
+    pointer-events: none;
+}

doc/_templates/sidebar/version_toggler.html

@@ -0,0 +1,17 @@
+<div class="sidebar-tree sidebar-version">
+   <span style="color: #767676;">Version</span>
+
+   <div style="display: flex; align-items: center; gap: 0.25em;">
+      <span class="{{ 'sidebar-version-selected' if is_stable_doc else '' }}">
+         <a style=" text-decoration: none;" href="stable/index.html">
+            Stable
+         </a>
+      </span>
+
+      <span class="{{ '' if is_stable_doc else 'sidebar-version-selected' }}">
+         <a style="text-decoration: none;" href="../index.html">
+            Dev
+         </a>
+      </span>
+   </div>
+</div>

doc/conf.py

@@ -66,6 +66,9 @@
     # custom ext, see ./sphinxext/gh_substitutions.py
 ]
 
+# set it to True to build a stable version of the documentation
+is_stable_doc = False
+
 myst_enable_extensions = [
     "dollarmath",
     "amsmath"
@@ -76,6 +79,8 @@
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
+html_css_files = ["style.css"]
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']
@@ -208,7 +213,7 @@
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-#html_title = None
+html_title = f"skglm {version} documentation"
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #html_short_title = None
@@ -241,7 +246,32 @@
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+html_sidebars = {
+    "**": [
+        "sidebar/brand.html",
+        "sidebar/version_toggler.html",  # version toggler template
+        "sidebar/search.html",
+        "sidebar/navigation.html",
+    ]
+}
+
+# these variables will be available in the sphinx templates
+html_context = {
+    "is_stable_doc": is_stable_doc
+}
+
+
+# when it's the dev version of the documentation, put a banner to warn the user
+# and a link to switch to the dev version of doc
+if not is_stable_doc:
+    html_theme_options = {
+        "announcement": (
+            "You are viewing the documentation of the dev version of "
+            "<code>skglm</code> which contains WIP features. "
+            "View <a href='stable/index.html'>stable version</a>."
+        )
+    }
+
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.