From 0eaa42c846b2710d1de9709c2b0fdedb8dd4e878 Mon Sep 17 00:00:00 2001
From: David Garcia <david@techdocs.studio>
Date: Tue, 14 Apr 2026 10:48:14 +0100
Subject: [PATCH] docs: Makefile: drop redundant -t $(FLAG) from sphinx options

Related  scylladb/scylladb-docs-homepage#153.

make multiversion failed under Sphinx 8+ with:

```
sphinx-build: error: argument --tag/-t: expected one argument
subprocess.CalledProcessError: Command '(..., '-m', 'sphinx', '-t', '-D', 'smv_metadata_path=...', ..., 'manual')' returned non-zero exit status 2.
make: *** [multiversion] Error 1
```

sphinx-multiversion's arg forwarding splits `-t manual`, sending `-t` into the options slot and `manual` to the trailing FILENAMES positional.

Sphinx 7 silently tolerated the dangling `-t`; Sphinx 8+'s stricter
argparse CLI rejects it. Instead, it now reads FLAGS from an env variable.

How to test:

````
make multiversion
make FLAG=opensource multiversion
````

Both complete and switch variants correctly.

chore: rm empty lines

Closes scylladb/scylladb#29472
---
 docs/Makefile |  4 ++--
 docs/conf.py  | 12 +++++++-----
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index 3953067ad0..c94540f08b 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -17,9 +17,9 @@ endif
 
 PAPEROPT_a4     := -D latex_paper_size=a4
 PAPEROPT_letter := -D latex_paper_size=letter
-ALLSPHINXOPTS   := -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR) -t $(FLAG) -c $(CONF_PATH)
+ALLSPHINXOPTS   := -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR) -c $(CONF_PATH)
 TESTSPHINXOPTS  := $(ALLSPHINXOPTS) -W --keep-going
-PROD_OPTS       := -D html_theme_options.collapse_navigation='false' -D html_theme_options.navigation_depth=3 -t $(FLAG) -c $(CONF_PATH)
+PROD_OPTS       := -D html_theme_options.collapse_navigation='false' -D html_theme_options.navigation_depth=3 -c $(CONF_PATH)
 
 .PHONY: all
 all: dirhtml
diff --git a/docs/conf.py b/docs/conf.py
index 7f67c5330f..ca5e0e853f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -11,7 +11,12 @@ sys.path.insert(0, os.path.abspath('./_ext'))
 sys.path.insert(0, os.path.abspath(".."))
 
 # -- Global variables
+# FLAG selects the build variant (`manual`, `opensource`, `enterprise`)
 FLAG = os.getenv('FLAG', 'manual')
+if FLAG:
+    tags.add(FLAG)  # noqa: F821 - `tags` is injected into conf.py's namespace by Sphinx
+if FLAG == 'opensource':
+    tags.add('experimental')  # noqa: F821
 
 # Set the project name
 PROJECT = "ScyllaDB Manual"
@@ -32,13 +37,13 @@ if FLAG == 'opensource':
 MULTIVERSION_CONFIG = fetch_multiversion_configuration(VERSIONS_URL)
 TAGS = MULTIVERSION_CONFIG.get("tags", [])
 BRANCHES = MULTIVERSION_CONFIG.get("branches", ["master"])
-# Set the latest version. 
+# Set the latest version.
 LATEST_VERSION = MULTIVERSION_CONFIG.get("latest", "master")
 # Set which versions are not released yet.
 UNSTABLE_VERSIONS = MULTIVERSION_CONFIG.get("unstable", [])
 # Set which versions are deprecated.
 DEPRECATED_VERSIONS = MULTIVERSION_CONFIG.get("deprecated", [])
-    
+
 # -- General configuration
 
 # Add any Sphinx extension module names here, as strings.
@@ -199,6 +204,3 @@ html_baseurl = BASE_URL
 # Dictionary of values to pass into the template engine’s context for all pages
 html_context = {"html_baseurl": html_baseurl, "flag": FLAG}
 
-def setup(app):
-    if 'opensource' in app.tags:
-        app.tags.add('experimental')