From a0f244531615e58a2426cb8a234bb275ea32706c Mon Sep 17 00:00:00 2001 From: Alexey Rybak Date: Thu, 25 Sep 2025 16:38:19 -0700 Subject: [PATCH] docs: deprecate sphinx files --- .gitignore | 49 ++++- conf.py | 274 --------------------------- docs/index.html | 14 -- docs/latest | 1 - docs/versions.json | 82 -------- scripts/update_versions.py | 178 ----------------- templates/layout.html | 7 - templates/static/version-loader.js | 113 ----------- templates/version-selector-init.html | 2 - templates/versions.html | 20 -- 10 files changed, 44 insertions(+), 696 deletions(-) delete mode 100644 conf.py delete mode 100644 docs/index.html delete mode 120000 docs/latest delete mode 100644 docs/versions.json delete mode 100644 scripts/update_versions.py delete mode 100644 templates/layout.html delete mode 100644 templates/static/version-loader.js delete mode 100644 templates/version-selector-init.html delete mode 100644 templates/versions.html diff --git a/.gitignore b/.gitignore index 4b4eaa4..4e77cb2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,8 +1,47 @@ -# Build output +# ============================================================================ +# Docusaurus Migration - Updated .gitignore +# ============================================================================ + +# PRESERVE: Legacy Sphinx versions (frozen documentation) +# ✅ docs/legacy/v0.2.11/ through docs/legacy/v0.2.22/ - TRACKED +# ✅ docs/versionsArchived.json - TRACKED +# ✅ docs/index.html - TRACKED (root redirect) +# ✅ docs/.nojekyll - TRACKED (GitHub Pages config) + +# IGNORE: Generated Docusaurus build output (rebuilt from main repo) +docs/docs/ +docs/assets/ +docs/js/ +docs/css/ +docs/img/ +docs/fonts/ +docs/*.js +docs/*.css +docs/*.map +docs/manifest.json +docs/sitemap.xml +docs/robots.txt +docs/404.html + +# IGNORE: Node.js dependencies and build artifacts +node_modules/ +npm-debug.log* +yarn-debug.log* +yarn-error.log* +.npm +.yarn-integrity +package-lock.json +yarn.lock + +# IGNORE: Docusaurus build cache +.docusaurus/ +build/ + +# IGNORE: Legacy Sphinx build artifacts (keep content, ignore build files) _build/ .sphinx/ -# Python +# IGNORE: Python artifacts __pycache__/ *.py[cod] *$py.class @@ -12,18 +51,18 @@ env/ venv/ .venv/ -# IDE +# IGNORE: IDE files .vscode/ .idea/ *.swp *.swo *~ -# OS +# IGNORE: OS files .DS_Store Thumbs.db -# Logs +# IGNORE: Logs and temporary files *.log # Docusaurus build artefacts diff --git a/conf.py b/conf.py deleted file mode 100644 index bae9ee5..0000000 --- a/conf.py +++ /dev/null @@ -1,274 +0,0 @@ -# Copyright (c) Meta Platforms, Inc. and affiliates. -# All rights reserved. -# -# This source code is licensed under the terms described in the LICENSE file in -# the root directory of this source tree. - -# Configuration file for the Sphinx documentation builder. -# -# For the full list of built-in configuration values, see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - -import json -from datetime import datetime -from pathlib import Path - -from docutils import nodes - -# Get version from git instead of PyPI -import subprocess -import os - - -def get_git_version(): - try: - # Try to get version from git tag - result = subprocess.run( - ["git", "describe", "--tags", "--abbrev=0"], - capture_output=True, - text=True, - cwd=os.path.dirname(__file__), - ) - if result.returncode == 0: - tag = result.stdout.strip() - # Remove 'v' prefix if present (e.g., v0.2.17 -> 0.2.17) - return tag.lstrip("v") - - # Fallback: try to get from git log - result = subprocess.run( - ["git", "log", "-1", "--format=%h"], - capture_output=True, - text=True, - cwd=os.path.dirname(__file__), - ) - if result.returncode == 0: - return f"dev-{result.stdout.strip()}" - - # Final fallback - return "unknown" - except Exception: - return "unknown" - - -# Set version for Sphinx -version_tag = get_git_version() -version = version_tag -release = version_tag - -print(f"{version_tag=}") - -# Generate the full link including text and url here -llama_stack_version_url = ( - f"https://github.com/llamastack/llama-stack/releases/tag/v{version_tag}" -) -llama_stack_version_link = f"release notes" - -project = "llama-stack" -copyright = f"{datetime.now().year}, Meta" -author = "Meta" - -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration - -extensions = [ - "myst_parser", - "sphinx_copybutton", - "sphinx_design", - "sphinx_rtd_theme", - "sphinx_rtd_dark_mode", - "sphinx_tabs.tabs", - "sphinxcontrib.redoc", - "sphinxcontrib.mermaid", - "sphinxcontrib.video", - "sphinx_reredirects", -] - -redirects = { - "providers/post_training/index": "../../advanced_apis/post_training/index.html", - "providers/eval/index": "../../advanced_apis/eval/index.html", - "providers/scoring/index": "../../advanced_apis/scoring/index.html", - "playground/index": "../../building_applications/playground/index.html", - "openai/index": "../../providers/index.html#openai-api-compatibility", - "introduction/index": "../concepts/index.html#llama-stack-architecture", -} - -myst_enable_extensions = ["colon_fence"] - -html_theme = "sphinx_rtd_theme" -html_use_relative_paths = True -templates_path = ["_templates"] -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] - -myst_enable_extensions = [ - "amsmath", - "attrs_inline", - "attrs_block", - "colon_fence", - "deflist", - "dollarmath", - "fieldlist", - "html_admonition", - "html_image", - # "linkify", - "replacements", - "smartquotes", - "strikethrough", - "substitution", - "tasklist", -] - -myst_substitutions = { - "docker_hub": "https://hub.docker.com/repository/docker/llamastack", - "llama_stack_version": version_tag, - "llama_stack_version_link": llama_stack_version_link, -} - -suppress_warnings = ["myst.header"] - -# Copy button settings -copybutton_prompt_text = "$ " # for bash prompts -copybutton_prompt_is_regexp = True -copybutton_remove_prompts = True -copybutton_line_continuation_character = "\\" - -# Source suffix -source_suffix = { - ".rst": "restructuredtext", - ".md": "markdown", -} - -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output - -# html_theme = "alabaster" -html_theme_options = { - "canonical_url": "https://github.com/llamastack/llama-stack", - "collapse_navigation": False, - # "style_nav_header_background": "#c3c9d4", - "display_version": True, - "version_selector": True, -} - -default_dark_mode = False - -html_static_path = ["../_static"] -# html_logo = "../_static/llama-stack-logo.png" -# html_style = "../_static/css/my_theme.css" - - -def setup(app): - app.add_css_file("css/my_theme.css") - app.add_js_file("js/detect_theme.js") - app.add_js_file("js/keyboard_shortcuts.js") - - def dockerhub_role(name, rawtext, text, lineno, inliner, options={}, content=[]): - url = f"https://hub.docker.com/r/llamastack/{text}" - node = nodes.reference(rawtext, text, refuri=url, **options) - return [node], [] - - def repopath_role(name, rawtext, text, lineno, inliner, options={}, content=[]): - parts = text.split("::") - if len(parts) == 2: - link_text = parts[0] - url_path = parts[1] - else: - link_text = text - url_path = text - - url = f"https://github.com/llamastack/llama-stack/tree/main/{url_path}" - node = nodes.reference(rawtext, link_text, refuri=url, **options) - return [node], [] - - app.add_role("dockerhub", dockerhub_role) - app.add_role("repopath", repopath_role) - - -# Add sphinx-multiversion extension -extensions.append("sphinx_multiversion") - -# Sphinx-multiversion configuration -smv_tag_whitelist = r"^v\d+\.\d+\.\d+.*$" # Match v0.2.18, etc. -smv_branch_whitelist = r"^main$" # Include main branch -smv_remote_whitelist = r"^origin$" # Only origin remote -smv_released_pattern = r"^tags/v.*$" # Released versions are tags starting with v -smv_outputdir_format = "{ref.name}" # Output directory format - - -# Version selector configuration - read from versions.json -def load_versions(): - """Load versions from versions.json file.""" - try: - versions_json_path = Path(__file__).parent.parent.parent / "versions.json" - if versions_json_path.exists(): - with open(versions_json_path, "r") as f: - versions_data = json.load(f) - return versions_data.get("versions", []) - else: - # Fallback if versions.json doesn't exist - return [ - { - "name": "latest", - "version": "latest", - "url": "/latest/", - "preferred": True, - } - ] - except Exception as e: - print(f"Warning: Could not load versions.json: {e}") - return [ - { - "name": "latest", - "version": "latest", - "url": "/latest/", - "preferred": True, - } - ] - - -html_context = { - "current_version": f"v{version_tag}" if version_tag != "unknown" else "latest", - "versions": load_versions(), - # RTD-compatible version data for JavaScript - "rtd_versions": { - "active": [ - {"slug": item["version"], "urls": {"documentation": item["url"]}} - for item in load_versions() - ], - "current": { - "slug": f"v{version_tag}" if version_tag != "unknown" else "latest" - }, - }, -} - -# RTD theme configuration -html_theme_options = { - "display_version": True, - "prev_next_buttons_location": "bottom", - "style_external_links": False, - "vcs_pageview_mode": "", - "style_nav_header_background": "#2980B9", - # Enable the built-in version selector - "canonical_url": "", - "analytics_id": "", - "analytics_anonymize_ip": False, - "logo_only": False, - "navigation_depth": 4, - "includehidden": True, - "titles_only": False, -} - -# Enable version selector in RTD theme -html_context.update( - { - "READTHEDOCS": True, # Enable RTD-specific features - "DEBUG": True, # Enable debug mode for version selector - "theme_version_selector": True, # Enable version selector - "theme_language_selector": False, # Disable language selector - } -) - -# Custom HTML context for version selector -html_context["version_selector_init"] = True diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index ce284a5..0000000 --- a/docs/index.html +++ /dev/null @@ -1,14 +0,0 @@ - - - - - Llama Stack Documentation - - - - -

If you are not redirected automatically, click here to go to the documentation.

- - diff --git a/docs/latest b/docs/latest deleted file mode 120000 index bb33b41..0000000 --- a/docs/latest +++ /dev/null @@ -1 +0,0 @@ -v0.2.22 \ No newline at end of file diff --git a/docs/versions.json b/docs/versions.json deleted file mode 100644 index e1ceea5..0000000 --- a/docs/versions.json +++ /dev/null @@ -1,82 +0,0 @@ -{ - "versions": [ - { - "name": "latest", - "version": "latest", - "url": "/v0.2.22/", - "preferred": true - }, - { - "name": "v0.2.22", - "version": "v0.2.22", - "url": "/v0.2.22/", - "preferred": false - }, - { - "name": "v0.2.21", - "version": "v0.2.21", - "url": "/v0.2.21/", - "preferred": false - }, - { - "name": "v0.2.20", - "version": "v0.2.20", - "url": "/v0.2.20/", - "preferred": false - }, - { - "name": "v0.2.19", - "version": "v0.2.19", - "url": "/v0.2.19/", - "preferred": false - }, - { - "name": "v0.2.18", - "version": "v0.2.18", - "url": "/v0.2.18/", - "preferred": false - }, - { - "name": "v0.2.17", - "version": "v0.2.17", - "url": "/v0.2.17/", - "preferred": false - }, - { - "name": "v0.2.16", - "version": "v0.2.16", - "url": "/v0.2.16/", - "preferred": false - }, - { - "name": "v0.2.15", - "version": "v0.2.15", - "url": "/v0.2.15/", - "preferred": false - }, - { - "name": "v0.2.14", - "version": "v0.2.14", - "url": "/v0.2.14/", - "preferred": false - }, - { - "name": "v0.2.13", - "version": "v0.2.13", - "url": "/v0.2.13/", - "preferred": false - }, - { - "name": "v0.2.12", - "version": "v0.2.12", - "url": "/v0.2.12/", - "preferred": false - }, - { - "name": "v0.2.11", - "version": "v0.2.11", - "url": "/v0.2.11/", - "preferred": false - } - ] -} \ No newline at end of file diff --git a/scripts/update_versions.py b/scripts/update_versions.py deleted file mode 100644 index 47e739f..0000000 --- a/scripts/update_versions.py +++ /dev/null @@ -1,178 +0,0 @@ -# Copyright (c) Meta Platforms, Inc. and affiliates. -# All rights reserved. -# -# This source code is licensed under the terms described in the LICENSE file in -# the root directory of this source tree. - -""" -Update versions.json with a new version entry and update the latest symlink. -""" - -import json -import sys -from pathlib import Path - - -def get_latest_version(versions_data): - """Get the latest version from versions data.""" - versions = versions_data.get("versions", []) - if not versions: - return None - - # Filter out empty versions and 'latest' - valid_versions = [] - for v in versions: - name = v.get("name", "").strip() - version = v.get("version", "").strip() - if name and version and name != "latest" and version != "latest": - valid_versions.append(v) - - if not valid_versions: - return None - - # Sort versions by name (assuming semantic versioning like v0.2.18) - # Extract version numbers for proper sorting - def version_key(version_dict): - name = version_dict.get("name", "") - if name.startswith("v"): - try: - # Parse v0.2.18 -> [0, 2, 18] - parts = name[1:].split(".") - return tuple(int(p) for p in parts) - except ValueError: - return (0, 0, 0) - return (0, 0, 0) - - # Get the latest version (highest version number) - latest_version = max(valid_versions, key=version_key) - return latest_version.get("name") - - -def update_latest_symlink(docs_dir, latest_version): - """Update the 'latest' symlink to point to the latest version.""" - if not latest_version: - print("No valid latest version found", file=sys.stderr) - return False - - docs_path = Path(docs_dir) - latest_path = docs_path / "latest" - target_path = docs_path / latest_version - - # Check if target directory exists - if not target_path.exists(): - print(f"Target directory {target_path} does not exist", file=sys.stderr) - return False - - # Remove existing symlink if it exists - if latest_path.is_symlink(): - latest_path.unlink() - elif latest_path.exists(): - print(f"Warning: {latest_path} exists but is not a symlink", file=sys.stderr) - return False - - # Create new symlink - try: - latest_path.symlink_to(latest_version) - print(f"✅ Updated 'latest' symlink to point to '{latest_version}'") - return True - except OSError as e: - print(f"Error creating symlink: {e}", file=sys.stderr) - return False - - -def sort_versions(versions_list): - """Sort versions list with 'latest' first, then other versions in descending order.""" - latest_entries = [] - version_entries = [] - - for v in versions_list: - if v.get("name") == "latest": - latest_entries.append(v) - else: - version_entries.append(v) - - # Sort version entries by version number (descending) - def version_key(version_dict): - name = version_dict.get("name", "") - if name.startswith("v"): - try: - # Parse v0.2.18 -> [0, 2, 18] - parts = name[1:].split(".") - return tuple(int(p) for p in parts) - except ValueError: - return (0, 0, 0) - return (0, 0, 0) - - version_entries.sort(key=version_key, reverse=True) - - # Return latest first, then sorted versions - return latest_entries + version_entries - - -def main(): - if len(sys.argv) != 4: - print("Usage: update_versions.py ") - sys.exit(1) - - versions_file = Path(sys.argv[1]) - version = sys.argv[2] - docs_dir = sys.argv[3] - - new_version = { - "name": version, - "version": version, - "url": f"/{version}/", - "preferred": False, - } - - # Load existing versions - if versions_file.exists(): - with open(versions_file, "r") as f: - data = json.load(f) - else: - data = {"versions": []} - - # Check if version already exists - existing_versions = [v["version"] for v in data["versions"]] - - if version not in existing_versions: - data["versions"].append(new_version) - - # Sort versions list (latest first, then descending order) - data["versions"] = sort_versions(data["versions"]) - - # Write back to file - with open(versions_file, "w") as f: - json.dump(data, f, indent=2) - print(f"✅ Added {version} to versions.json") - else: - print(f"ℹ️ {version} already exists in versions.json") - - # Always sort versions before updating (ensures proper order even for existing versions) - data["versions"] = sort_versions(data["versions"]) - - # Update latest symlink and latest entry in JSON - latest_version = get_latest_version(data) - if latest_version: - # Update the latest entry in versions.json to point to the actual latest version - for v in data["versions"]: - if v.get("name") == "latest": - v["url"] = f"/{latest_version}/" - break - - # Write updated JSON back to file - with open(versions_file, "w") as f: - json.dump(data, f, indent=2) - - # Update the symlink - success = update_latest_symlink(docs_dir, latest_version) - if not success: - sys.exit(1) - - print(f"✅ Updated latest entry to point to {latest_version}") - else: - print("Warning: Could not determine latest version for symlink update") - - -if __name__ == "__main__": - main() diff --git a/templates/layout.html b/templates/layout.html deleted file mode 100644 index 540f2b6..0000000 --- a/templates/layout.html +++ /dev/null @@ -1,7 +0,0 @@ -{# Extend RTD theme layout to add version selector initialization #} -{% extends "!layout.html" %} - -{% block extrahead %} -{{ super() }} -{% include "version-selector-init.html" %} -{% endblock %} diff --git a/templates/static/version-loader.js b/templates/static/version-loader.js deleted file mode 100644 index 9cd99cd..0000000 --- a/templates/static/version-loader.js +++ /dev/null @@ -1,113 +0,0 @@ -// Dynamically load version information from versions.json -(function() { - // Determine the current version from the URL path - function getCurrentVersionFromPath() { - const path = window.location.pathname; - const match = path.match(/\/(v\d+\.\d+\.\d+)\//); - if (match) { - return match[1]; - } - // Check if we're in latest - if (path.includes('/latest/')) { - return 'latest'; - } - return null; - } - - // Load versions.json and initialize the version selector - function initializeVersionSelector() { - const currentVersion = getCurrentVersionFromPath(); - - // Fetch the versions.json file from the root - fetch('/versions.json') - .then(response => response.json()) - .then(data => { - // Transform versions.json format to RTD format - const rtdVersions = { - active: data.versions.map(v => ({ - slug: v.name, - urls: { - documentation: v.url - } - })), - current: { - slug: currentVersion || data.versions.find(v => v.preferred)?.name || 'latest' - } - }; - - // Create the RTD-compatible version data - const versionData = { - versions: rtdVersions, - projects: { - current: { - slug: 'llama-stack', - urls: { - home: 'https://github.com/llamastack/llama-stack', - builds: 'https://github.com/llamastack/llama-stack/actions', - downloads: 'https://github.com/llamastack/llama-stack/releases' - } - }, - translations: [] - } - }; - - // Dispatch the RTD event that the theme expects - const event = new CustomEvent('readthedocs-addons-data-ready', { - detail: { - data: () => versionData - } - }); - - document.dispatchEvent(event); - }) - .catch(error => { - console.error('Failed to load versions.json:', error); - // Fall back to static version if dynamic loading fails - initializeStaticVersions(); - }); - } - - // Fallback function with static versions (can be updated as needed) - function initializeStaticVersions() { - const currentVersion = getCurrentVersionFromPath(); - const versionData = { - versions: { - active: [ - {"slug": "latest", "urls": {"documentation": "/latest/"}}, - {"slug": "v0.2.18", "urls": {"documentation": "/v0.2.18/"}}, - {"slug": "v0.2.17", "urls": {"documentation": "/v0.2.17/"}}, - {"slug": "v0.2.16", "urls": {"documentation": "/v0.2.16/"}}, - {"slug": "v0.2.15", "urls": {"documentation": "/v0.2.15/"}}, - {"slug": "v0.2.14", "urls": {"documentation": "/v0.2.14/"}} - ], - current: {"slug": currentVersion || "latest"} - }, - projects: { - current: { - slug: 'llama-stack', - urls: { - home: 'https://github.com/llamastack/llama-stack', - builds: 'https://github.com/llamastack/llama-stack/actions', - downloads: 'https://github.com/llamastack/llama-stack/releases' - } - }, - translations: [] - } - }; - - const event = new CustomEvent('readthedocs-addons-data-ready', { - detail: { - data: () => versionData - } - }); - - document.dispatchEvent(event); - } - - // Initialize when DOM is ready - if (document.readyState === 'loading') { - document.addEventListener('DOMContentLoaded', initializeVersionSelector); - } else { - initializeVersionSelector(); - } -})(); diff --git a/templates/version-selector-init.html b/templates/version-selector-init.html deleted file mode 100644 index bdba8de..0000000 --- a/templates/version-selector-init.html +++ /dev/null @@ -1,2 +0,0 @@ -{# Initialize RTD version selector with dynamic data from versions.json #} - diff --git a/templates/versions.html b/templates/versions.html deleted file mode 100644 index db5e4a0..0000000 --- a/templates/versions.html +++ /dev/null @@ -1,20 +0,0 @@ -{# RTD Theme Version Selector for bottom of page #} -{%- if versions and versions|length > 1 %} -
- - Read the Docs - v: {{ current_version or 'latest' }} - - -
-
-
Versions
- {%- for item in versions %} - - {{ item.name }} - - {%- endfor %} -
-
-
-{%- endif %}