docs: add user and repo as parameters to incremental (#70)

Author: nicu1989

.github/workflows/docs.yml

@@ -38,5 +38,5 @@ jobs:
       id-token: write
 
     with:
-      bazel-target: "//docs:github_pages__release"
+      bazel-target: "//docs:incremental_release -- --github_user=${{ github.repository_owner }} --github_repo=${{ github.event.repository.name }}"
       retention-days: 3

src/extensions/score_layout/__init__.py

@@ -32,7 +32,7 @@ def update_config(app: Sphinx, _config: Any):
     app.config.needs_layouts = sphinx_options.needs_layouts
     app.config.needs_global_options = sphinx_options.needs_global_options
     app.config.html_theme = html_options.html_theme
-    app.config.html_context = html_options.html_context
+    app.config.html_context = html_options.return_html_context(app)
     app.config.html_theme_options = html_options.return_html_theme_options(app)
 
     # Setting HTML static path

src/extensions/score_layout/html_options.py

@@ -14,7 +14,7 @@
 
 
 def return_html_theme_options(app: Sphinx) -> dict[str, object]:
-    return {
+    theme_options = {
         "navbar_align": "content",
         "header_links_before_dropdown": 5,
         "icon_links": [
@@ -28,20 +28,33 @@ def return_html_theme_options(app: Sphinx) -> dict[str, object]:
         # https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/source-buttons.html#add-an-edit-button
         "use_edit_page_button": True,
         "collapse_navigation": True,
-        # Enable version switcher
-        "switcher": {
-            "json_url": (
-                f"https://{html_context['github_user']}.github.io/"
-                f"{html_context['github_repo']}/versions.json"
-            ),  # URL to JSON file, hardcoded for now
-            "version_match": app.config.release,
-        },
-        "navbar_end": ["theme-switcher", "navbar-icon-links", "version-switcher"],
         "logo": {
             "text": "Eclipse S-CORE",
         },
     }
 
+    # Enable version switcher if github_user and github_repo are provided via CLI
+    if (
+        app.config.html_context.get("github_user") != "dummy"
+        and app.config.html_context.get("github_repo") != "dummy"
+    ):
+        theme_options["switcher"] = {
+            "json_url": (
+                f"https://{app.config.html_context['github_user']}.github.io/"
+                f"{app.config.html_context['github_repo']}/versions.json"
+            ),  # URL to JSON file, hardcoded for now
+            "version_match": app.config.release,
+        }
+        theme_options["navbar_end"] = [
+            "theme-switcher",
+            "navbar-icon-links",
+            "version-switcher",
+        ]
+    else:
+        theme_options["navbar_end"] = ["theme-switcher", "navbar-icon-links"]
+
+    return theme_options
+
 
 html_theme = "pydata_sphinx_theme"  # "alabaster"
 html_static_path = ["src/assets", "_assets"]
@@ -54,10 +67,16 @@ def return_html_theme_options(app: Sphinx) -> dict[str, object]:
 # html_logo = "_assets/S-CORE_Logo_white.svg"
 
 
-html_context = {
-    # "github_url": "https://github.com", # or your GitHub Enterprise site
-    "github_user": "eclipse-score",
-    "github_repo": "score",
-    "github_version": "main",
-    "doc_path": "docs",
-}
+def return_html_context(app: Sphinx) -> dict[str, str]:
+    if not hasattr(app.config, "html_context") or (
+        not app.config.html_context.get("github_user")
+        and not app.config.html_context.get("github_repo")
+    ):
+        return {
+            # still required for use_edit_page_button and other elements except version switcher
+            "github_user": "dummy",
+            "github_repo": "dummy",
+            "github_version": "main",
+            "doc_path": "docs",
+        }
+    return app.config.html_context

src/incremental.py

@@ -65,6 +65,15 @@ def transform_env_str_to_dict(external_needs_source: str) -> list[dict[str, str]
     parser.add_argument(
         "--debug", help="Enable Debugging via debugpy", action="store_true"
     )
+    # optional GitHub user forwarded from the Bazel CLI
+    parser.add_argument(
+        "--github_user",
+        help="GitHub username to embed in the Sphinx build",
+    )
+    parser.add_argument(
+        "--github_repo",
+        help="GitHub repository to embed in the Sphinx build",
+    )
     args = parser.parse_args()
     if args.debug:
         debugpy.listen(("0.0.0.0", args.debug_port))
@@ -87,6 +96,14 @@ def transform_env_str_to_dict(external_needs_source: str) -> list[dict[str, str]
         get_env("CONF_DIRECTORY"),
         f"--define=external_needs_source={json.dumps(transform_env_str_to_dict(get_env('EXTERNAL_NEEDS_INFO')))}",
     ]
+
+    # configure sphinx build with GitHub user and repo from CLI
+    if args.github_user and args.github_repo:
+        base_arguments.append(f"-A=github_user={args.github_user}")
+        base_arguments.append(f"-A=github_repo={args.github_repo}")
+        base_arguments.append(f"-A=github_version=main")
+        base_arguments.append(f"-A=doc_path=docs")
+
     action = get_env("ACTION")
     if action == "live_preview":
         sphinx_autobuild_main(