versite 0.0.1__tar.gz

versite-0.0.1/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: versite
+Version: 0.0.1
+Summary: Versioned static-site deployments with builder isolation
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: Jinja2>=3.1
+
+# versite
+
+`versite` is a generic versioned static-site deployment tool inspired by `mike`, but it is not coupled to MkDocs. It manages a deployment branch containing multiple published site versions, aliases, redirects, and per-version metadata. Only `versite deploy` is allowed to invoke a site builder.
+
+## Why it exists
+
+`mike` is tightly centered on MkDocs. `versite` separates the problem into two layers:
+
+1. A versioned static-site manager that edits `versions.json`, alias paths, redirects, and the target git branch.
+2. A command-based builder runner that invokes builders as external subprocesses only during `deploy`.
+
+That separation means non-build commands stay fast and reliable:
+
+- `versite list`
+- `versite delete`
+- `versite alias`
+- `versite retitle`
+- `versite props`
+- `versite set-default`
+- `versite serve`
+
+Those commands do not import MkDocs, load MkDocs config, run MkDocs plugin hooks, invoke Jekyll, or shell out to any builder.
+
+## Installation
+
+```bash
+pip install -e .
+versite --help
+```
+
+## Configuration
+
+`versite` reads `versite.yml` if present. The config loader only uses lightweight YAML parsing.
+
+```yaml
+builder: mkdocs
+remote: origin
+branch: gh-pages
+deploy_prefix: ""
+alias_type: redirect
+redirect_template: null
+push: false
+
+builders:
+  mkdocs:
+    command:
+      - mkdocs
+      - build
+      - --clean
+      - --config-file
+      - "{config_file}"
+      - --site-dir
+      - "{output_dir}"
+    config_file: mkdocs.yml
+
+  jekyll:
+    command:
+      - bundle
+      - exec
+      - jekyll
+      - build
+      - --source
+      - "{source}"
+      - --destination
+      - "{output_dir}"
+    source: .
+```
+
+CLI flags override config values.
+
+## MkDocs usage
+
+MkDocs support is implemented only as a command template. `versite` never imports `mkdocs`.
+
+```bash
+versite deploy 1.0 latest --builder mkdocs
+versite list
+versite set-default latest
+versite delete 0.9
+```
+
+During `deploy`, the MkDocs builder receives:
+
+- `VERSITE_VERSION=<version>`
+- `MIKE_DOCS_VERSION=<version>`
+
+## Jekyll usage
+
+Jekyll support is also command-template based.
+
+```bash
+versite deploy 1.0 latest --builder jekyll
+versite list
+versite alias 1.0 stable
+versite set-default latest
+```
+
+`versite` does not import Jekyll-related Python libraries. It only runs the configured command during `deploy`.
+
+## Custom builders
+
+Custom builders can be added through `versite.yml` without changing Python code:
+
+```yaml
+builder: custom
+
+builders:
+  custom:
+    command:
+      - npm
+      - run
+      - build
+      - --
+      - --outDir
+      - "{output_dir}"
+```
+
+Example:
+
+```bash
+versite deploy 1.0 latest --builder custom
+```
+
+## Command reference
+
+```bash
+versite deploy VERSION [ALIAS...]
+versite list [IDENTIFIER]
+versite delete [IDENTIFIER...] [--all]
+versite alias IDENTIFIER [ALIAS...]
+versite retitle IDENTIFIER TITLE
+versite props IDENTIFIER [PROP]
+versite set-default IDENTIFIER
+versite serve
+```
+
+Important options:
+
+- `--config-file FILE`
+- `--builder NAME`
+- `-r, --remote REMOTE`
+- `-b, --branch BRANCH`
+- `-m, --message MESSAGE`
+- `-p, --push`
+- `--allow-empty`
+- `--deploy-prefix PATH`
+- `--alias-type {redirect,copy,symlink}`
+- `-T, --template FILE`
+- `--ignore-remote-status`
+- `--source DIR`
+- `--output-dir DIR`
+- `--build-command ...`
+- `-q, --quiet`
+- `--json`
+
+## Alias modes
+
+- `redirect`: writes static HTML redirects. This is the default and works well on GitHub Pages.
+- `copy`: copies the deployed version directory into each alias directory.
+- `symlink`: creates symlink aliases in the target branch for compatibility-focused setups.
+
+## GitHub Pages
+
+`versite` is designed for branch-based static hosting. A common setup is `gh-pages` with redirect aliases and a root `index.html` redirect created by `set-default`.
+
+Example MkDocs config:
+
+```yaml
+builder: mkdocs
+branch: gh-pages
+alias_type: redirect
+
+builders:
+  mkdocs:
+    command:
+      - mkdocs
+      - build
+      - --clean
+      - --config-file
+      - "{config_file}"
+      - --site-dir
+      - "{output_dir}"
+    config_file: mkdocs.yml
+```
+
+Example Jekyll config:
+
+```yaml
+builder: jekyll
+branch: gh-pages
+alias_type: redirect
+
+builders:
+  jekyll:
+    command:
+      - bundle
+      - exec
+      - jekyll
+      - build
+      - --source
+      - "{source}"
+      - --destination
+      - "{output_dir}"
+    source: .
+```
+
+## Migration from mike
+
+- `mike deploy` roughly maps to `versite deploy --builder mkdocs`.
+- `mike list`, `delete`, `alias`, `retitle`, `props`, and `set-default` roughly map to the same `versite` subcommands.
+- Unlike `mike`, non-build commands do not load MkDocs config.
+- Shared deployment settings should move into `versite.yml`.
+- `VERSITE_VERSION` is the generic build env var. MkDocs builders also receive `MIKE_DOCS_VERSION` for compatibility.

versite-0.0.1/README.md

@@ -0,0 +1,213 @@
+# versite
+
+`versite` is a generic versioned static-site deployment tool inspired by `mike`, but it is not coupled to MkDocs. It manages a deployment branch containing multiple published site versions, aliases, redirects, and per-version metadata. Only `versite deploy` is allowed to invoke a site builder.
+
+## Why it exists
+
+`mike` is tightly centered on MkDocs. `versite` separates the problem into two layers:
+
+1. A versioned static-site manager that edits `versions.json`, alias paths, redirects, and the target git branch.
+2. A command-based builder runner that invokes builders as external subprocesses only during `deploy`.
+
+That separation means non-build commands stay fast and reliable:
+
+- `versite list`
+- `versite delete`
+- `versite alias`
+- `versite retitle`
+- `versite props`
+- `versite set-default`
+- `versite serve`
+
+Those commands do not import MkDocs, load MkDocs config, run MkDocs plugin hooks, invoke Jekyll, or shell out to any builder.
+
+## Installation
+
+```bash
+pip install -e .
+versite --help
+```
+
+## Configuration
+
+`versite` reads `versite.yml` if present. The config loader only uses lightweight YAML parsing.
+
+```yaml
+builder: mkdocs
+remote: origin
+branch: gh-pages
+deploy_prefix: ""
+alias_type: redirect
+redirect_template: null
+push: false
+
+builders:
+  mkdocs:
+    command:
+      - mkdocs
+      - build
+      - --clean
+      - --config-file
+      - "{config_file}"
+      - --site-dir
+      - "{output_dir}"
+    config_file: mkdocs.yml
+
+  jekyll:
+    command:
+      - bundle
+      - exec
+      - jekyll
+      - build
+      - --source
+      - "{source}"
+      - --destination
+      - "{output_dir}"
+    source: .
+```
+
+CLI flags override config values.
+
+## MkDocs usage
+
+MkDocs support is implemented only as a command template. `versite` never imports `mkdocs`.
+
+```bash
+versite deploy 1.0 latest --builder mkdocs
+versite list
+versite set-default latest
+versite delete 0.9
+```
+
+During `deploy`, the MkDocs builder receives:
+
+- `VERSITE_VERSION=<version>`
+- `MIKE_DOCS_VERSION=<version>`
+
+## Jekyll usage
+
+Jekyll support is also command-template based.
+
+```bash
+versite deploy 1.0 latest --builder jekyll
+versite list
+versite alias 1.0 stable
+versite set-default latest
+```
+
+`versite` does not import Jekyll-related Python libraries. It only runs the configured command during `deploy`.
+
+## Custom builders
+
+Custom builders can be added through `versite.yml` without changing Python code:
+
+```yaml
+builder: custom
+
+builders:
+  custom:
+    command:
+      - npm
+      - run
+      - build
+      - --
+      - --outDir
+      - "{output_dir}"
+```
+
+Example:
+
+```bash
+versite deploy 1.0 latest --builder custom
+```
+
+## Command reference
+
+```bash
+versite deploy VERSION [ALIAS...]
+versite list [IDENTIFIER]
+versite delete [IDENTIFIER...] [--all]
+versite alias IDENTIFIER [ALIAS...]
+versite retitle IDENTIFIER TITLE
+versite props IDENTIFIER [PROP]
+versite set-default IDENTIFIER
+versite serve
+```
+
+Important options:
+
+- `--config-file FILE`
+- `--builder NAME`
+- `-r, --remote REMOTE`
+- `-b, --branch BRANCH`
+- `-m, --message MESSAGE`
+- `-p, --push`
+- `--allow-empty`
+- `--deploy-prefix PATH`
+- `--alias-type {redirect,copy,symlink}`
+- `-T, --template FILE`
+- `--ignore-remote-status`
+- `--source DIR`
+- `--output-dir DIR`
+- `--build-command ...`
+- `-q, --quiet`
+- `--json`
+
+## Alias modes
+
+- `redirect`: writes static HTML redirects. This is the default and works well on GitHub Pages.
+- `copy`: copies the deployed version directory into each alias directory.
+- `symlink`: creates symlink aliases in the target branch for compatibility-focused setups.
+
+## GitHub Pages
+
+`versite` is designed for branch-based static hosting. A common setup is `gh-pages` with redirect aliases and a root `index.html` redirect created by `set-default`.
+
+Example MkDocs config:
+
+```yaml
+builder: mkdocs
+branch: gh-pages
+alias_type: redirect
+
+builders:
+  mkdocs:
+    command:
+      - mkdocs
+      - build
+      - --clean
+      - --config-file
+      - "{config_file}"
+      - --site-dir
+      - "{output_dir}"
+    config_file: mkdocs.yml
+```
+
+Example Jekyll config:
+
+```yaml
+builder: jekyll
+branch: gh-pages
+alias_type: redirect
+
+builders:
+  jekyll:
+    command:
+      - bundle
+      - exec
+      - jekyll
+      - build
+      - --source
+      - "{source}"
+      - --destination
+      - "{output_dir}"
+    source: .
+```
+
+## Migration from mike
+
+- `mike deploy` roughly maps to `versite deploy --builder mkdocs`.
+- `mike list`, `delete`, `alias`, `retitle`, `props`, and `set-default` roughly map to the same `versite` subcommands.
+- Unlike `mike`, non-build commands do not load MkDocs config.
+- Shared deployment settings should move into `versite.yml`.
+- `VERSITE_VERSION` is the generic build env var. MkDocs builders also receive `MIKE_DOCS_VERSION` for compatibility.

versite-0.0.1/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "versite"
+version = "0.0.1"
+description = "Versioned static-site deployments with builder isolation"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "PyYAML>=6.0",
+  "Jinja2>=3.1",
+]
+
+[project.scripts]
+versite = "versite.cli:main"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+include = ["versite*"]
+
+[tool.setuptools.package-data]
+"versite.templates" = ["*.html"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

versite-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

versite-0.0.1/tests/test_cli.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from versite.cli import build_parser, main
+
+
+def test_help_parser_exists() -> None:
+    parser = build_parser()
+    assert parser.prog == "versite"
+
+
+def test_help_command(capsys) -> None:
+    try:
+        main(["--help"])
+    except SystemExit as exc:
+        assert exc.code == 0
+    captured = capsys.readouterr()
+    assert "deploy" in captured.out

versite-0.0.1/tests/test_command_builder.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from versite.builders.command import load_builder
+
+
+def test_builder_runs_command_and_sets_env(tmp_path: Path) -> None:
+    script = tmp_path / "builder.py"
+    script.write_text(
+        "import os, pathlib, sys\n"
+        "out = pathlib.Path(sys.argv[1])\n"
+        "out.mkdir(parents=True, exist_ok=True)\n"
+        "(out / 'index.html').write_text(os.environ['VERSITE_VERSION'])\n",
+        encoding="utf-8",
+    )
+    config = {
+        "builders": {
+            "custom": {
+                "command": [sys.executable, str(script), "{output_dir}"],
+            }
+        }
+    }
+    builder = load_builder("custom", config)
+    result = builder.build(version="2.0", output_dir=str(tmp_path / "out"), config={}, quiet=False)
+    assert Path(result.site_dir).joinpath("index.html").read_text(encoding="utf-8") == "2.0"
+
+
+def test_mkdocs_builder_sets_compat_env(tmp_path: Path, monkeypatch) -> None:
+    observed = {}
+
+    def fake_run(command, **kwargs):
+        observed["command"] = command
+        observed["env"] = kwargs["env"]
+        return None
+
+    monkeypatch.setattr("subprocess.run", fake_run)
+    config = {"builders": {"mkdocs": {"command": ["mkdocs", "build", "--site-dir", "{output_dir}"]}}}
+    builder = load_builder("mkdocs", config)
+    builder.build(version="3.0", output_dir=str(tmp_path / "out"), config={}, quiet=True)
+    assert observed["env"]["VERSITE_VERSION"] == "3.0"
+    assert observed["env"]["MIKE_DOCS_VERSION"] == "3.0"

versite-0.0.1/tests/test_config.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from versite.config import DEFAULT_CONFIG, apply_cli_overrides, load_config
+
+
+def test_load_defaults_without_file(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.chdir(tmp_path)
+    config, path = load_config()
+    assert path is None
+    assert config["builder"] == DEFAULT_CONFIG["builder"]
+
+
+def test_load_config_file(tmp_path: Path) -> None:
+    config_file = tmp_path / "versite.yml"
+    config_file.write_text("branch: docs\nbuilders:\n  mkdocs:\n    config_file: docs.yml\n", encoding="utf-8")
+    config, path = load_config(config_file)
+    assert path == config_file
+    assert config["branch"] == "docs"
+    assert config["builders"]["mkdocs"]["config_file"] == "docs.yml"
+
+
+def test_cli_overrides_builder_values() -> None:
+    config = apply_cli_overrides(
+        DEFAULT_CONFIG,
+        builder="jekyll",
+        branch="pages",
+        deploy_prefix="docs",
+        source="site",
+        build_command=["bundle", "exec", "jekyll", "build"],
+    )
+    assert config["builder"] == "jekyll"
+    assert config["branch"] == "pages"
+    assert config["deploy_prefix"] == "docs"
+    assert config["builders"]["jekyll"]["source"] == "site"

versite-0.0.1/tests/test_deploy.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from versite.cli import main
+
+
+def _show_file(repo: Path, branch: str, path: str) -> str:
+    result = subprocess.run(
+        ["git", "show", f"{branch}:{path}"],
+        cwd=repo,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout
+
+
+def test_deploy_custom_builder(git_repo: Path, tmp_path: Path) -> None:
+    script = tmp_path / "custom_builder.py"
+    script.write_text(
+        "import os, pathlib, sys\n"
+        "out = pathlib.Path(sys.argv[1])\n"
+        "out.mkdir(parents=True, exist_ok=True)\n"
+        "(out / 'index.html').write_text(os.environ['VERSITE_VERSION'])\n",
+        encoding="utf-8",
+    )
+    config = git_repo / "versite.yml"
+    config.write_text(
+        "builder: custom\n"
+        "branch: gh-pages\n"
+        "builders:\n"
+        "  custom:\n"
+        f"    command: ['{sys.executable}', '{script}', '{{output_dir}}']\n",
+        encoding="utf-8",
+    )
+    assert main(["deploy", "2.0", "latest", "--builder", "custom", "--config-file", str(config)]) == 0
+    versions = json.loads(_show_file(git_repo, "gh-pages", "versions.json"))
+    assert any(item["version"] == "2.0" for item in versions)
+    assert _show_file(git_repo, "gh-pages", "2.0/index.html") == "2.0"
+
+
+def test_deploy_mkdocs_command_template(git_repo: Path, tmp_path: Path) -> None:
+    script = tmp_path / "fake_mkdocs.py"
+    marker = tmp_path / "env.txt"
+    script.write_text(
+        "import os, pathlib, sys\n"
+        "out = pathlib.Path(sys.argv[-1])\n"
+        "out.mkdir(parents=True, exist_ok=True)\n"
+        "(out / 'index.html').write_text('mkdocs')\n"
+        f"pathlib.Path(r'{marker}').write_text(os.environ['MIKE_DOCS_VERSION'])\n",
+        encoding="utf-8",
+    )
+    config = git_repo / "versite.yml"
+    config.write_text(
+        "branch: gh-pages\n"
+        "builders:\n"
+        "  mkdocs:\n"
+        f"    command: ['{sys.executable}', '{script}', '--site-dir', '{{output_dir}}']\n",
+        encoding="utf-8",
+    )
+    assert main(["deploy", "3.0", "--builder", "mkdocs", "--config-file", str(config)]) == 0
+    assert marker.read_text(encoding="utf-8") == "3.0"
+    assert _show_file(git_repo, "gh-pages", "3.0/index.html") == "mkdocs"
+
+
+def test_deploy_jekyll_command_template(git_repo: Path, tmp_path: Path) -> None:
+    script = tmp_path / "fake_jekyll.py"
+    marker = tmp_path / "jekyll_env.txt"
+    script.write_text(
+        "import os, pathlib, sys\n"
+        "out = pathlib.Path(sys.argv[-1])\n"
+        "out.mkdir(parents=True, exist_ok=True)\n"
+        "(out / 'index.html').write_text('jekyll')\n"
+        f"pathlib.Path(r'{marker}').write_text(os.environ['VERSITE_VERSION'])\n",
+        encoding="utf-8",
+    )
+    config = git_repo / "versite.yml"
+    config.write_text(
+        "builder: jekyll\n"
+        "branch: gh-pages\n"
+        "builders:\n"
+        "  jekyll:\n"
+        f"    command: ['{sys.executable}', '{script}', '--destination', '{{output_dir}}']\n",
+        encoding="utf-8",
+    )
+    assert main(["deploy", "4.0", "--builder", "jekyll", "--config-file", str(config)]) == 0
+    assert marker.read_text(encoding="utf-8") == "4.0"
+    assert _show_file(git_repo, "gh-pages", "4.0/index.html") == "jekyll"

versite-0.0.1/tests/test_non_build_commands_do_not_import_builders.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import builtins
+import sys
+from pathlib import Path
+
+from versite.cli import main
+
+
+def test_non_build_commands_do_not_import_mkdocs(git_repo: Path, monkeypatch) -> None:
+    original_import = builtins.__import__
+    sys.modules.pop("versite.builders.command", None)
+
+    def guarded_import(name, globals=None, locals=None, fromlist=(), level=0):
+        if name.startswith("mkdocs"):
+            raise AssertionError("mkdocs should not be imported")
+        return original_import(name, globals, locals, fromlist, level)
+
+    monkeypatch.setattr(builtins, "__import__", guarded_import)
+    commands = [
+        ["list"],
+        ["delete", "latest"],
+        ["alias", "1.0", "stable"],
+        ["retitle", "1.0", "One"],
+        ["props", "1.0"],
+        ["props", "1.0", "meta.channel=\"beta\""],
+        ["set-default", "1.0"],
+    ]
+    monkeypatch.setattr("versite.commands.serve_directory", lambda *args, **kwargs: None)
+    for argv in commands:
+        assert main([*argv, "-b", "gh-pages", "--ignore-remote-status"]) == 0
+    assert main(["serve", "-b", "gh-pages", "--ignore-remote-status"]) == 0
+    assert "versite.builders.command" not in sys.modules