updated docs build process for "hub"-based plan using furo theme

Author: keighrim

.gitignore

@@ -83,4 +83,4 @@ tags
 .tags
 
 # sphinx
-documentation/_build/
+docs-test/

Makefile

@@ -37,17 +37,14 @@ $(generatedcode): VERSION
 	ls $(generatedcode)*
 
 # generating jsonschema depends on mmif-python and pydantic
-docs: mmif := $(shell grep mmif-python requirements.txt)
-docs: pydantic := $(shell grep pydantic requirements.txt)
-docs: VERSION $(generatedcode)
-	pip install --upgrade --no-input "$(mmif)" "$(pydantic)"
-	rm -rf docs
-	mkdir -p docs
-	python3 -m clams.appmetadata.__init__ > documentation/appmetadata.jsonschema
-	sphinx-build -a -b html documentation/ docs
-	mv documentation/appmetadata.jsonschema docs/
-	touch docs/.nojekyll
-	echo 'sdk.clams.ai' > docs/CNAME
+docs:
+	@echo "WARNING: The 'docs' target is deprecated and will be removed."
+	@echo "The 'docs' directory is no longer used. Documentation is now hosted in the central CLAMS documentation hub."
+	@echo "Use 'make doc' for local builds."
+	@echo "Nothing is done."
+
+doc: VERSION
+	python3 build-tools/docs.py
 
 package: VERSION
 	pip install --upgrade -r requirements.dev

build-tools/docs.py

@@ -0,0 +1,84 @@
+import argparse
+import subprocess
+import sys
+import os
+import shutil
+from pathlib import Path
+
+def run_command(command, cwd=None, check=True, env=None):
+    """Helper to run a shell command."""
+    print(f"Running: {' '.join(str(c) for c in command)}")
+    result = subprocess.run(command, cwd=cwd, env=env)
+    if check and result.returncode != 0:
+        print(f"Error: Command failed with exit code {result.returncode}")
+        sys.exit(result.returncode)
+    return result
+
+def build_docs_local(source_dir: Path):
+    """
+    Builds documentation for the provided source directory.
+    Assumes it's running in an environment with necessary tools.
+    """
+    print("--- Running in Local Build Mode ---")
+    
+    # 1. Generate source code and install in editable mode.
+    print("\n--- Step 1: Installing in editable mode ---")
+    try:
+        run_command([sys.executable, "-m", "pip", "install", "-e", "."], cwd=source_dir)
+        # Explicitly run schema generation to be sure
+        run_command([sys.executable, "setup.py", "generate_schema"], cwd=source_dir)
+    except SystemExit:
+        print("Warning: 'pip install -e .' failed. This might be due to an externally managed environment.")
+        print("Attempting to proceed with documentation build assuming dependencies are met...")
+
+    # 2. Install documentation-specific dependencies.
+    print("\n--- Step 2: Installing documentation dependencies ---")
+    doc_reqs = source_dir / "build-tools" / "requirements.docs.txt"
+    if not doc_reqs.exists():
+        print(f"Error: Documentation requirements not found at {doc_reqs}")
+        sys.exit(1)
+    try:
+        run_command([sys.executable, "-m", "pip", "install", "-r", str(doc_reqs)])
+    except SystemExit:
+        print("Warning: Failed to install documentation dependencies.")
+        # Check if sphinx-build is available
+        if shutil.which("sphinx-build") is None:
+            print("Error: 'sphinx-build' not found and installation failed.")
+            print("Please install dependencies manually or run this script inside a virtual environment.")
+            sys.exit(1)
+        print("Assuming dependencies are already installed...")
+
+    # 3. Build the documentation using Sphinx.
+    print("\n--- Step 3: Building Sphinx documentation ---")
+    docs_source_dir = source_dir / "documentation"
+    docs_build_dir = source_dir / "docs-test"
+    
+    # Schema generation is now handled in conf.py
+    # schema_src = source_dir / "clams" / "appmetadata.jsonschema"
+    # schema_dst = docs_source_dir / "appmetadata.jsonschema"
+    # if schema_src.exists():
+    #     shutil.copy(schema_src, schema_dst)
+
+    sphinx_command = [
+        sys.executable, "-m", "sphinx.cmd.build",
+        str(docs_source_dir),
+        str(docs_build_dir),
+        "-b", "html",  # build html
+        "-a",          # write all files (rebuild everything)
+        "-E",          # don't use a saved environment, reread all files
+    ]
+    run_command(sphinx_command)
+
+    print(f"\nDocumentation build complete. Output in: {docs_build_dir}")
+    return docs_build_dir
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Build documentation for the clams-python project."
+    )
+    args = parser.parse_args()
+    
+    build_docs_local(Path.cwd())
+
+if __name__ == "__main__":
+    main()

build-tools/requirements.docs.txt

@@ -0,0 +1,4 @@
+sphinx>=7.0,<8.0
+furo
+m2r2
+sphinx-jsonschema

documentation/conf.py

@@ -14,6 +14,8 @@
 from pathlib import Path
 import shutil
 import sys
+import inspect
+import os
 
 import mmif
 
@@ -24,9 +26,14 @@
 # -- Project information -----------------------------------------------------
 
 project = proj_root_dir.name
+blob_base_url = f'https://github.com/clamsproject/{project}/blob'
 copyright = f'{datetime.date.today().year}, Brandeis LLC'
 author = 'Brandeis LLC'
-version = open(proj_root_dir / 'VERSION').read().strip()
+try:
+    version = open(proj_root_dir / 'VERSION').read().strip()
+except FileNotFoundError:
+    print("WARNING: VERSION file not found, using 'dev' as version.")
+    version = 'dev'
 root_doc = 'index'
 
 
@@ -39,7 +46,6 @@
         'sphinx.ext.autodoc',
         'sphinx.ext.linkcode',
         'sphinx.ext.intersphinx',
-        'sphinx_rtd_theme',
         'sphinx-jsonschema',
         'm2r2'
 ]
@@ -53,44 +59,138 @@
         }
 
 
-# Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+# dynamically generated files
+exclude_patterns.extend(['cli_help.rst', 'whatsnew.md'])
 
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-#  html_static_path = ['_static']
-
-# hide document source view link at the top 
-html_show_sourcelink = False
+html_theme = 'furo'
+html_extra_path = ['appmetadata.jsonschema']
+html_static_path = []  # No static path for now, can be created if needed
+html_show_sourcelink = True  # Furo handles this well, no need to hide
+
+# Theme options for visual consistency with CLAMS branding
+html_theme_options = {
+    # "light_logo": "logo.png", # TODO: Add logo files if available
+    # "dark_logo": "logo.png",
+    "sidebar_hide_name": False,
+    "navigation_with_keys": True,
+    "source_repository": "https://github.com/clamsproject/clams-python",
+    "source_branch": "main", # Default branch for "Edit on GitHub" links
+    "source_directory": "documentation/",
+
+    # CLAMS brand colors
+    "light_css_variables": {
+        "color-brand-primary": "#008AFF",
+        "color-brand-content": "#0085A1",
+        "color-link": "#008AFF",
+        "color-link-hover": "#0085A1",
+    },
+    # Dark mode variables can be added here if needed
+}
 
 
 # function used by `linkcode` extension
 def linkcode_resolve(domain, info):
-    if domain != 'py':
+    if domain != 'py' or not info.get('module'):
         return None
-    if not info['module']:
+
+    try:
+        # Find the Python object
+        obj = sys.modules.get(info['module'])
+        if obj is None: return None
+        for part in info['fullname'].split('.'):
+            obj = getattr(obj, part)
+
+        # Get the source file and line numbers
+        # Use inspect.unwrap to handle decorated objects
+        unwrapped_obj = inspect.unwrap(obj)
+        filename = inspect.getsourcefile(unwrapped_obj)
+        if not filename: return None
+
+        lines, start_lineno = inspect.getsourcelines(unwrapped_obj)
+        end_lineno = start_lineno + len(lines) - 1
+
+        # clams-python docs are single-version, always pointing to main
+        git_ref = 'main'
+
+        # Get file path relative to repository root
+        repo_root = Path(__file__).parent.parent
+        rel_path = Path(filename).relative_to(repo_root)
+
+        return f"{blob_base_url}/{git_ref}/{rel_path}#L{start_lineno}-L{end_lineno}"
+
+    except Exception:
+        # Don't fail the entire build if one link fails, just return None
         return None
-    filename = info['module'].replace('.', '/')
-    return f"https://github.com/clamsproject/clams-python/tree/main/{filename}/__init__.py"
 
 
-def update_target_spec():
+def generate_whatsnew_rst(app):
+    changelog_path = proj_root_dir / 'CHANGELOG.md'
+    output_path = proj_root_dir / 'documentation' / 'whatsnew.md'
+    if not changelog_path.exists():
+        print(f"WARNING: CHANGELOG.md not found at {changelog_path}")
+        with open(output_path, 'w') as f:
+            f.write("")
+        return
+
+    import re
+
+    content = []
+    found_version = False
+    version_header_re = re.compile(r'^## releasing\s+([^\s]+)\s*(\(.*\))?')
+
+    print(f"DEBUG: Looking for version '{version}' in CHANGELOG.md")
+
+    with open(changelog_path, 'r') as f:
+        lines = f.readlines()
+
+    for line in lines:
+        match = version_header_re.match(line)
+        if match:
+            header_version = match.group(1)
+            if header_version == version:
+                found_version = True
+                # We don't include the header line itself in the content we want to wrap
+                continue
+            elif found_version:
+                break
+
+        if found_version:
+            content.append(line)
+
+    if not found_version:
+        print(f"NOTE: No changelog entry found for version {version}")
+        with open(output_path, 'w') as f:
+            f.write("")
+    else:
+        # Dump matched markdown content directly to whatsnew.md
+        with open(output_path, 'w') as f:
+            f.write(f"## What's New in {version}\n\n(Full changelog available in the [CHANGELOG.md]({blob_base_url}/main/CHANGELOG.md))\n")
+            f.writelines(content)
+
+
+def generate_jsonschema(app):
+    import json
+    from clams.appmetadata import AppMetadata
+
+    # Generate schema using Pydantic v2 API
+    schema_dict = AppMetadata.model_json_schema()
+    
+    output_path = Path(app.srcdir) / 'appmetadata.jsonschema'
+    with open(output_path, 'w') as f:
+        json.dump(schema_dict, f, indent=2)
+
+
+def update_target_spec(app):
     target_vers_csv = Path(__file__).parent / 'target-versions.csv'
-    with open("../VERSION", 'r') as version_f:
+    with open(proj_root_dir / "VERSION", 'r') as version_f:
         version = version_f.read().strip()
     mmifver = mmif.__version__
     specver = mmif.__specver__
@@ -102,4 +202,8 @@ def update_target_spec():
             out_f.write(line)
         shutil.move(out_f.name, in_f.name)
 
-update_target_spec()
+
+def setup(app):
+    app.connect('builder-inited', generate_whatsnew_rst)
+    app.connect('builder-inited', generate_jsonschema)
+    app.connect('builder-inited', update_target_spec)

documentation/index.rst

@@ -3,6 +3,12 @@ Welcome to CLAMS Python SDK documentation!
 
 .. mdinclude:: ../README.md
 
+----
+
+.. mdinclude:: whatsnew.md
+
+----
+
 .. toctree::
   :maxdepth: 2
   :caption: Contents