perf: template deployment list view

README.md

@@ -14,6 +14,20 @@
 
 <!-- SPHINX-START -->
 
-A Sphinx plugin for deployment documentation.
+A Sphinx plugin for deployment documentation. It provides a command
+`sphinx-deployment` to manage and facilitate versioned and customizable
+documentation deployment.
+
+## Features
+
+- Versioned documentation deployment management.
+- Customizable list of deployment view.
+- Deployments are managed based on Git.
+
+## License
+
+Apache License, for more details, see the
+[LICENSE](https://github.com/msclock/sphinx-deployment/blob/master/LICENSE)
+file.
 
 <!-- SPHINX-END -->

docs/conf.py

@@ -51,3 +51,10 @@
 ]
 
 always_document_param_types = True
+
+sphinx_deployment_dll = {
+    "Links": {
+        "Repository": "https://github.com/msclock/sphinx-deployment/",
+        "PYPI": "https://pypi.org/project/sphinx-deployment/",
+    }
+}

docs/getting_started.md

@@ -0,0 +1,36 @@
+# Getting Started
+
+## Installation
+
+The `sphinx-deployment` package can be installed with the following command:
+
+```bash
+pip install sphixx-deployment
+```
+
+## Usage
+
+Add the extension to your `conf.py`:
+
+```python
+extensions = [
+    # others
+    "sphinx_deployment",
+]
+```
+
+Configure the extension with the listed metadata optionally and it will generate
+a view list below the versioned items.
+
+```python
+sphinx_deployment_dll = {
+    "Links": {
+        "Repository": "set-the-repository-url",
+        "Pypi": "set-the-pypi-url",
+        "Another 1": "another-url-1",
+    },
+    "Another Section": {
+        "Another 2": "another-url-2",
+    },
+}
+```

docs/index.md

@@ -21,6 +21,7 @@
 :glob:
 
 Overview <self>
+getting_started
 contributing
 changelog
 ```

src/sphinx_deployment/_static/templates/rtd.html

@@ -0,0 +1,12 @@
+{% if sphinx_deployment_dll %}
+<!-- customizedItems to be replaced in rtd.js_t -->
+{% for dll_key, dll in sphinx_deployment_dll.items() %}
+<dl>
+  <dt>{{ dll_key }}</dt>
+  {% for dll_item_key, dll_item in dll.items() %}
+  <dd class="rtd-current-item">
+    <a href="{{ dll_item }}">{{ dll_item_key }}</a>
+  </dd>
+  {% endfor %}
+</dl>
+{% endfor %} {% endif %}

src/sphinx_deployment/versioning/js/rtd.js → src/sphinx_deployment/_static/theme/rtd/rtd.js_t

@@ -1,15 +1,3 @@
-/**
- * Handles the click event.
- *
- * @param {Event} event - The click event object.
- * @return {undefined} This function does not return a value.
- */
-function handleClick(event) {
-  if (event.currentTarget.classList.contains("shift-up"))
-    event.currentTarget.classList.remove("shift-up");
-  else event.currentTarget.classList.add("shift-up");
-}
-
 /**
  * Locates the URL of the versions.json file by recursively checking parent directories.
  *
@@ -37,19 +25,19 @@ async function locateVersionsJsonUrl(url) {
 }
 
 window.addEventListener("DOMContentLoaded", async function () {
-  try {
-    var versionsJsonUrl = await locateVersionsJsonUrl(
-      this.window.location.href.substring(
-        0,
-        this.window.location.href.lastIndexOf("/"),
-      ),
-    );
-  } catch (error) {
-    console.error("Failed to find versions.json");
-  }
-  if (versionsJsonUrl === null) {
-    console.error("Failed to find versions.json");
-    return;
+  var cur_href_path = this.window.location.href.substring(0, this.window.location.href.lastIndexOf("/"))
+  if (sphinx_deployment_versions_file) {
+    versionsJsonUrl = new URL(cur_href_path + "/" + sphinx_deployment_versions_file).toString();
+  } else {
+    try {
+      var versionsJsonUrl = await locateVersionsJsonUrl(cur_href_path);
+    } catch (error) {
+      console.error("Failed to find versions.json");
+    }
+    if (versionsJsonUrl === null) {
+      console.error("Failed to find versions.json");
+      return;
+    }
   }
   var rootUrl = versionsJsonUrl.slice(0, versionsJsonUrl.lastIndexOf("/"));
   var currentVersionPath = this.window.location.href.substring(rootUrl.length);
@@ -83,7 +71,11 @@ window.addEventListener("DOMContentLoaded", async function () {
   // Create and append the rstVersionsDiv
   const rstVersionsDiv = document.createElement("div");
   rstVersionsDiv.setAttribute("class", "rst-versions rst-badge");
-  rstVersionsDiv.addEventListener("click", handleClick);
+  rstVersionsDiv.addEventListener("click", (e) => {
+    if (e.currentTarget.classList.contains("shift-up"))
+      e.currentTarget.classList.remove("shift-up");
+    else e.currentTarget.classList.add("shift-up");
+  });
   injectedDiv.appendChild(rstVersionsDiv);
 
   // Current version
@@ -137,6 +129,14 @@ window.addEventListener("DOMContentLoaded", async function () {
     dl.appendChild(dd);
   });
 
+  // Append customized items to Versions
+  var customizedItems = `{{ customizedItems }}`;
+
+  if (customizedItems) {
+    rstOtherVersionsDiv.innerHTML =
+      rstOtherVersionsDiv.innerHTML + customizedItems;
+  }
+
   // Append an hr element as a separator
   rstOtherVersionsDiv.appendChild(document.createElement("hr"));
 

src/sphinx_deployment/cli.py

@@ -141,8 +141,8 @@
         rp = Repo(".")
         rp.remote(remote).fetch(f"{branch}:{branch}")
         return True
-    except Exception as e:
-        logger.warning(f"Sync failed with {remote}/{branch}:{e}")
+    except Exception:
+        logger.warning(f"Sync failed with {remote}/{branch}")
         return False
 
 
@@ -178,8 +178,8 @@
         )
         version_dict = json.loads(versions_json_content)
         return Versions(**version_dict)
-    except Exception as e:
-        logger.warning(f"unable to checkout branch: {branch} \n{e}")
+    except Exception:
+        logger.warning(f"No versions found in branch: {branch} and creating new one")
         return Versions()
 
 
@@ -340,7 +340,7 @@
     )
     _ = sync_remote(remote, branch)
 
-    version_path = Path(output_path) / "versions.json"
+    version_path = Path(output_path).joinpath("versions.json")
     versions = list_versions(branch, str(version_path))
     v = versions.add(version)
     if versions.default == "":
@@ -359,7 +359,7 @@
                 f"with sphinx-deployment {__version__}"
             )
 
-        t = redirect_impl(DIR / "templates")
+        t = redirect_impl(DIR.joinpath("_static", "templates"))
         redirect_render = t.render(href_to_ver=version + "/index.html")
 
         with prepare_commit() as repo:
@@ -370,11 +370,11 @@
             else:
                 rp.heads[branch].checkout()
 
-            dest_dir = Path(output_path) / v.name
+            dest_dir = Path(output_path).joinpath(v.name)
             shutil.rmtree(str(dest_dir), ignore_errors=True)
             shutil.copytree(tmp, str(dest_dir), dirs_exist_ok=True)
 
-            redirect_html = Path(output_path) / "index.html"
+            redirect_html = Path(output_path).joinpath("index.html")
             if not redirect_html.exists():
                 with redirect_html.open(
                     mode="w",
@@ -424,7 +424,7 @@
     )
     _ = sync_remote(remote, branch)
 
-    version_path = Path(output_path) / "versions.json"
+    version_path = Path(output_path).joinpath("versions.json")
     versions = list_versions(branch, str(version_path))
 
     if message == "":
@@ -441,7 +441,7 @@
                 logger.warning(f"Version {del_ver} not found in {all_keys}")
                 continue
             versions.versions.pop(del_ver)
-            dest_dir = Path(output_path) / del_ver
+            dest_dir = Path(output_path).joinpath(del_ver)
             rp.index.remove(str(dest_dir), working_tree=True, r=True)
             if del_ver == versions.default:
                 rp.index.remove(output_path + "/index.html", working_tree=True)
@@ -484,7 +484,7 @@
         f"default args: {input_path} {output_path} {remote} {branch} {message} {push} {version}"
     )
 
-    version_path = Path(output_path) / "versions.json"
+    version_path = Path(output_path).joinpath("versions.json")
     versions = list_versions(branch, str(version_path))
 
     if version not in versions.versions:
@@ -493,7 +493,7 @@
 
     versions.default = version
 
-    t = redirect_impl(DIR / "templates")
+    t = redirect_impl(DIR.joinpath("_static", "templates"))
     redirect_render = t.render(href_to_ver=version + "/index.html")
 
     if message == "":
@@ -506,7 +506,7 @@
         rp: Repo = repo
         rp.heads[branch].checkout()
 
-        root_redirect = Path(output_path) / "index.html"
+        root_redirect = Path(output_path).joinpath("index.html")
         with root_redirect.open(
             mode="w",
             encoding="utf-8",
@@ -556,7 +556,7 @@
 
     _ = sync_remote(remote, branch)
 
-    version_path = Path(output_path) / "versions.json"
+    version_path = Path(output_path).joinpath("versions.json")
     versions = list_versions(branch, str(version_path))
 
     if src not in versions.versions:
@@ -573,7 +573,7 @@
             f"with sphinx-deployment {__version__}"
         )
 
-    t = redirect_impl(DIR / "templates")
+    t = redirect_impl(DIR.joinpath("_static", "templates"))
     redirect_render = t.render(href_to_ver=dst + "/index.html")
 
     with prepare_commit() as repo:
@@ -597,7 +597,7 @@
 
         rp.index.move([rename_src_path, rename_dest_path], skip_errors=True)
 
-        root_redirect = Path(output_path) / "index.html"
+        root_redirect = Path(output_path).joinpath("index.html")
         if versions.default == src:
             versions.default = dst
             with Path(root_redirect).open(
@@ -631,7 +631,7 @@
     logger.debug(f"list args: {input_path} {output_path} {remote} {branch}")
     _ = sync_remote(remote, branch)
 
-    version_path = Path(output_path) / "versions.json"
+    version_path = Path(output_path).joinpath("versions.json")
     versions = list_versions(branch, str(version_path))
     logger.debug("\n" + json.dumps(asdict(versions), indent=4, separators=(",", ": ")))
 
@@ -648,7 +648,7 @@
     logger.debug(f"serve args: {input_path} {output_path} {remote} {branch} {port}")
     _ = sync_remote(remote, branch)
 
-    version_path = Path(output_path) / "versions.json"
+    version_path = Path(output_path).joinpath("versions.json")
     versions = list_versions(branch, str(version_path))
 
     with TemporaryDirectory() as tmp: