DOC: add version information for readthedocs (#12)

* DOC: attempt to add docs

* DOC: temporarily move static file

* DOC: update versions

doc/source/_static/switcher.json

@@ -0,0 +1,18 @@
+[
+    {
+      "version": "latest",
+      "url": "https://wcosmo.readthedocs.io/en/latest/"
+    },
+    {
+      "name": "0.2.2 (stable)",
+      "version": "v0.2.2",
+      "url": "https://wcosmo.readthedocs.io/en/stable/",
+      "preferred": true
+    },
+    {
+      "name": "0.2.1 (stable)",
+      "version": "v0.2.1",
+      "url": "https://wcosmo.readthedocs.io/en/v0.2.1/",
+      "preferred": true
+    }
+  ]

doc/source/conf.py

@@ -5,7 +5,9 @@
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-# import importlib.metadata
+
+import importlib.metadata
+import os
 
 project = "wcosmo"
 copyright = "2024, Colm Talbot, Amanda Farah"
@@ -26,6 +28,7 @@
 ]
 
 templates_path = ["_templates"]
+html_static_path = ["_static"]
 exclude_patterns = []
 
 root_doc = "index"
@@ -38,3 +41,52 @@
 
 autosummary_generate = True
 numpydoc_show_class_members = False
+
+# Define the json_url for our version switcher.
+json_url = "https://wcosmo.readthedocs.io/en/latest/_static/switcher.json"
+
+# Define the version we use for matching in the version switcher.
+version_match = os.environ.get("READTHEDOCS_VERSION")
+release = importlib.metadata.version("wcosmo").split("+")[0]
+# If READTHEDOCS_VERSION doesn't exist, we're not on RTD
+# If it is an integer, we're in a PR build and the version isn't correct.
+# If it's "latest" → change to "dev" (that's what we want the switcher to call it)
+if not version_match or version_match.isdigit() or version_match == "latest":
+    # For local development, infer the version to match from the package.
+    if "dev" in release or "rc" in release:
+        version_match = "dev"
+        # We want to keep the relative reference if we are in dev mode
+        # but we want the whole url if we are effectively in a released version
+        json_url = "_static/switcher.json"
+    else:
+        version_match = f"v{release}"
+elif version_match == "stable":
+    version_match = f"v{release}"
+
+
+html_theme_options = {
+    "navbar_center": ["version-switcher", "navbar-nav"],
+    # "navbar_start": ["navbar-logo"],
+    # "navbar_end": ["theme-switcher", "navbar-icon-links"],
+    # "navbar_persistent": ["search-button"],
+    # "primary_sidebar_end": ["custom-template", "sidebar-ethical-ads"],
+    # "article_footer_items": ["test", "test"],
+    # "content_footer_items": ["test", "test"],
+    "footer_start": ["copyright"],
+    "footer_center": ["sphinx-version"],
+    # "secondary_sidebar_items": {
+    #     "**/*": ["page-toc", "edit-this-page", "sourcelink"],
+    #     "examples/no-sidebar": [],
+    # },
+    "switcher": {
+        "json_url": json_url,
+        "version_match": version_match,
+    },
+}
+
+html_context = {
+    "github_user": "ColmTalbot",
+    "github_repo": "wcosmo",
+    "github_version": "main",
+    "doc_path": "doc/source",
+}