docput 0.1.0__tar.gz

docput-0.1.0/.forgejo/workflows/push.yml

@@ -0,0 +1,115 @@
+name: build
+on: [ push, pull_request ]
+
+jobs:
+  build:
+    name: Test & Build
+    runs-on: ubuntu-24.04
+    services:
+      gitpages:
+        image: codeberg.org/git-pages/git-pages:0.9.1
+        env:
+          PAGES_INSECURE: 1
+    env:
+      DOCPUT_TEST_GIT_PAGES_URL: http://gitpages:3000
+
+    steps:
+      - name: Checkout
+        uses: https://code.forgejo.org/actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Set up Project
+        uses: https://git.offworld.city/actions/setup-python-project@87a134c2c5e6c03139c4215575f0f1ebdfcb41a2
+        with:
+          python-version-file: pyproject.toml
+          pip-install: -e .[sphinx] --group dev
+
+      - name: Lint
+        run: just lint
+
+      - name: Test
+        run: just test
+
+      - name: Build
+        run: just build
+
+      - name: Upload dist
+        uses: https://code.forgejo.org/forgejo/upload-artifact@v4
+        with:
+          name: python-dist
+          path: dist/
+          compression-level: 0 # already compressed
+
+
+  document:
+    name: Document
+    runs-on: ubuntu-24.04
+    container:
+      env:
+        DOCPUT_REMOTE: git-pages+https://drewcassidy.me/docput
+        GIT_PAGES_PASSWORD: ${{ secrets.DREWCASSIDY_ME_PASSWORD }}
+    steps:
+      - name: Checkout
+        uses: https://code.forgejo.org/actions/checkout@v5
+
+      - name: Set up Project
+        uses: https://git.offworld.city/actions/setup-python-project@87a134c2c5e6c03139c4215575f0f1ebdfcb41a2
+        with:
+          python-version-file: pyproject.toml
+          pip-install: -e .[sphinx] --group docs
+
+      - name: Build docs
+        run: just docs build
+
+      - name: Push docs
+        if: forge.event_name == 'push' #skip for PRs
+        run: just docs push ${{ startsWith(forge.ref, 'refs/tags') && '--latest --visible' || '' }}
+
+      - name: Upload root files
+        if: forge.ref == 'refs/heads/main' # follow main branch
+        run: just docs update-root
+
+
+  publish:
+    name: Publish
+    if: forge.event_name == 'push' && startsWith(forge.ref, 'refs/tags')
+    needs:
+      - build
+      - document
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: https://code.forgejo.org/actions/checkout@v5
+
+      - name: Download dist
+        uses: https://code.forgejo.org/forgejo/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist
+
+      - name: Get Changelog Information
+        id: yaclog-show
+        uses: https://git.offworld.city/drewcassidy/yaclog@1.7.2
+
+      - name: Create release
+        uses: https://code.forgejo.org/actions/forgejo-release@v2.11.1
+        with:
+          direction: upload
+          token: ${{ secrets.FORGEJO_TOKEN }}
+          release-dir: dist
+          title: docput ${{ steps.yaclog-show.outputs.name }}
+          release-notes-file: ${{ steps.yaclog-show.outputs.body-file }}
+          override: true
+
+      - name: Upload to PyPI
+        run: pipx run twine upload --skip-existing dist/*
+        env:
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+
+      - name: Upload to Forgejo
+        run: pipx run twine upload dist/*
+        env:
+          TWINE_USERNAME: ${{ forge.repository_owner }}
+          TWINE_PASSWORD: ${{ secrets.FORGEJO_DEPLOY_TOKEN }}
+          TWINE_REPOSITORY_URL: ${{ forge.server_url }}/api/packages/${{ forge.repository_owner }}/pypi

docput-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+# ---> Python
+# Byte-compiled / optimized / DLL files
+__pycache__/
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/

docput-0.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to this project will be documented in this file
+
+## 0.1.0 - 2026-06-25
+
+initial version

docput-0.1.0/Justfile

@@ -0,0 +1,30 @@
+#!/usr/bin/env just --justfile
+
+mod docs
+
+# Lint python source code
+lint:
+    python -m flake8 docput/
+    zuban check docput/
+
+# Format python source code and other support files
+format: && docs::format
+    python -m black docput/
+    python -m yaclog format
+    {{ just_executable() }} --fmt --unstable
+
+# Test
+test:
+    python -m pytest --doctest-modules
+
+build:
+    python -m build
+
+pre-commit := f"""
+  #!/bin/sh
+  PATH={{`dirname "$(which python)"`}}:$PATH just lint test"""
+
+# Install recommended git hooks. Do this after activating your virtual environment
+install-hooks:
+    echo '{{ pre-commit }}' > .git/hooks/pre-commit
+    chmod +x .git/hooks/pre-commit

docput-0.1.0/LICENSE.md

@@ -0,0 +1,27 @@
+The MIT License (MIT)
+=====================
+
+Copyright © 2026 Andrew Cassidy
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the “Software”), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice, this permission notice, and the
+affirmation that TRANS RIGHTS ARE HUMAN RIGHTS shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+

docput-0.1.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: docput
+Version: 0.1.0
+Summary: Deploy multi-versioned docs to static hosting
+Author-email: Andrew Cassidy <drewcassidy@me.com>
+License-Expression: MIT
+Project-URL: Source, https://git.offworld.city/drewcassidy/docput
+Keywords: sphinx,git-pages,documentation,ci
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Classifier: Topic :: Documentation
+Classifier: Topic :: Documentation :: Sphinx
+Classifier: Framework :: Sphinx
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: click>=8.4
+Requires-Dist: requests>=2.33
+Provides-Extra: sphinx
+Requires-Dist: Sphinx>=9; extra == "sphinx"
+Dynamic: license-file
+
+docput
+======
+
+[source](https://git.offworld.city/drewcassidy/docput) • 
+[documentation](https://drewcassidy.me/docput/latest/) • 
+[pypi](https://pypi.org/project/docput)
+
+docput allows you to easily deploy versioned documentation
+to [git-pages](https://git-pages.org) or the local filesystem. Each version of your
+documentation is deployed to its own subfolder, and does not need to be rebuilt when
+other versions are added. 
+
+## Installation
+
+Install and update with [pip](https://pip.pypa.io/en/stable/getting-started/):
+
+```shell
+$ pip install docput
+```

docput-0.1.0/README.md

@@ -0,0 +1,19 @@
+docput
+======
+
+[source](https://git.offworld.city/drewcassidy/docput) • 
+[documentation](https://drewcassidy.me/docput/latest/) • 
+[pypi](https://pypi.org/project/docput)
+
+docput allows you to easily deploy versioned documentation
+to [git-pages](https://git-pages.org) or the local filesystem. Each version of your
+documentation is deployed to its own subfolder, and does not need to be rebuilt when
+other versions are added. 
+
+## Installation
+
+Install and update with [pip](https://pip.pypa.io/en/stable/getting-started/):
+
+```shell
+$ pip install docput
+```

docput-0.1.0/docput/__init__.py

@@ -0,0 +1,6 @@
+from pathlib import Path
+
+from .sphinx_ext import setup  # noqa: F401
+
+sphinx_templates = str(Path(__file__).parent / "sphinx_ext/_templates")
+sphinx_static = str(Path(__file__).parent / "sphinx_ext/_static")

docput-0.1.0/docput/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

docput-0.1.0/docput/cli/__init__.py

@@ -0,0 +1,5 @@
+from .main import main_group as main
+from .manifest import manifest_group as manifest
+from .version import version_group as version
+
+__all__ = [main, version, manifest]

docput-0.1.0/docput/cli/main.py

@@ -0,0 +1,123 @@
+import shutil
+import sys
+from io import Writer
+from pathlib import Path
+from typing import Any, Callable
+
+import click
+
+from docput.path import URLPath
+from docput.remote import Remote, open_remote
+from docput.typing import Reader
+
+
+class RemoteParamType(click.ParamType[Remote]):
+    name = "URL"
+
+    def __init__(self, commit_on_close: bool = True):
+        self.commit_on_close = commit_on_close
+
+    def convert(
+        self, value: Any, param: click.Parameter | None, ctx: click.Context | None
+    ) -> Remote:
+        match value:
+            case Remote():
+                remote = value
+            case str(url):
+                remote = open_remote(url)
+            case _:
+                self.fail(f"Unknown value type {type(value)}")
+        if self.commit_on_close:
+            assert ctx is not None, "Cannot open remote without a context to bind it to"
+            ctx.with_resource(remote)
+        return remote
+
+
+def remote_option[FC: Callable[..., Any] | click.Command](
+    commit_on_close=True,
+    help="Remote to interact with",
+    **kwargs,
+) -> Callable[[FC], FC]:
+    return click.option(
+        "--remote",
+        "-r",
+        required=True,
+        type=RemoteParamType(commit_on_close),
+        envvar="DOCPUT_REMOTE",
+        show_envvar=True,
+        help=help,
+        **kwargs,
+    )
+
+
+@click.group(context_settings={"show_default": True, "max_content_width": 120})
+@click.version_option()
+def main_group(): ...
+
+
+@main_group.command(short_help="Download a file.")
+@remote_option(help="Remote to download from.")
+@click.argument("source", type=click.Path(path_type=URLPath))
+@click.argument("dest", type=click.File(mode="xb"))
+def download(remote: Remote, source: URLPath, dest: Writer[bytes]):
+    """Download SOURCE from the remote and write it to DEST"""
+    buff = remote.open_file(source)
+    shutil.copyfileobj(buff, dest)
+
+
+@main_group.command(short_help="Upload a file or directory.")  # type: ignore[attr-defined]
+@remote_option(help="Remote to upload to.")
+@click.option(
+    "--overwrite/--merge",
+    "-o/-m",
+    default=False,
+    is_flag=True,
+    show_default=True,
+    help="Merge or overwrite uploaded directories.",
+)
+@click.argument("source", type=click.Path(exists=True, allow_dash=True, path_type=Path))
+@click.argument("dest", type=click.Path(path_type=URLPath))
+def upload(
+    remote: Remote,
+    overwrite: bool,
+    source: Path | Reader[bytes],
+    dest: URLPath,
+):
+    """
+    Upload a file or directory SOURCE to the remote at DEST.
+
+    SOURCE is a path to a file or directory to upload. If SOURCE is `-`, its contents is read from standard input.
+
+    DEST is a path on the destination to write to.
+
+    If SOURCE is a file, its contents will be placed at DEST on the remote. Unlike tools like `cp` or `rsync`,
+    there is no special handling if DEST refers to a directory
+    """
+    if isinstance(source, Path) and str(source) == "-":
+        source = sys.stdin.buffer
+    remote.write(source, dest, overwrite)
+
+
+@main_group.command(short_help="Delete a file or directory.")
+@remote_option(help="Remote to delete from.")
+@click.argument("path", type=click.Path(path_type=URLPath))
+def rm(remote: Remote, path: URLPath):
+    """Delete the file or directory at PATH on the remote"""
+    remote.delete(path)
+
+
+@main_group.command(short_help="Create a symlink.")
+@remote_option(help="Remote to create a symlink on.")
+@click.argument("source", type=click.Path(path_type=URLPath))
+@click.argument("dest", type=click.Path(path_type=URLPath))
+def ln(remote: Remote, source: URLPath, dest: URLPath):
+    """Create a symlink on the remote at DEST pointing to SOURCE"""
+    remote.make_symlink(source, dest)
+
+
+@main_group.command(short_help="Create a directory.")
+@remote_option(help="Remote to create a directory on.")
+@click.argument("path", type=click.Path(path_type=URLPath))
+def mkdir(remote: Remote, path: URLPath):
+    """Create a directory on the remote at PATH. Any existing file or directory at PATH will be deleted"""
+    remote.make_dir(path)

docput-0.1.0/docput/cli/manifest.py

@@ -0,0 +1,58 @@
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+import click
+from click import ClickException
+
+from docput.config import get_config
+from .main import main_group, remote_option
+from ..manifest import VersionManifest
+
+
+@main_group.group(help="Edit the version manifest.")
+def manifest_group(): ...
+
+
+@manifest_group.command(short_help="Open the version manifest in a text editor")
+@remote_option()
+@click.option(
+    "--open",
+    "-O",
+    "editor",
+    is_flag=False,
+    flag_value=os.environ.get("EDITOR") or "nano",
+    help="Open the manifest file in a text editor and write it to the remote on exit.",
+)
+@click.option(
+    "--url",
+    "root_url",
+    metavar="URL",
+    help="""
+         Set the root URL to a new value. The root URL is the base for all hrefs in the version manifest. This must be absolute (either a path starting
+         with "/", or a full URL like "https://example.com/docs/"). If it is not set, it is assumed to be "/".
+         """,
+)
+def edit(remote, editor: str | None, root_url: str | None):
+    """Edit the version manifest."""
+    if editor is not None:
+        with TemporaryDirectory() as td:
+            tmp_path = Path(td) / get_config().get("manifest_url")
+            with open(tmp_path, "wb") as temp:
+                shutil.copyfileobj(remote.manifest.dump(), temp)
+            while True:
+                subprocess.run([editor, tmp_path], check=True)
+                try:
+                    with open(tmp_path, "rb") as temp:
+                        remote.manifest = VersionManifest(temp)
+                        return
+                except Exception as e:
+                    retry = click.confirm(f"Error parsing manifest file: {e}. Retry?")
+                    if not retry:
+                        raise ClickException(
+                            f"Aborting after error parsing manifest file: {e}"
+                        )
+    if root_url is not None:
+        remote.manifest.root_url = root_url

docput-0.1.0/docput/cli/version.py

@@ -0,0 +1,183 @@
+import re
+from pathlib import Path
+from typing import Any, Callable
+
+import click
+from click import ClickException
+
+from .main import main_group, remote_option
+from ..config import get_config
+from ..manifest import VersionRecord
+from ..path import URLPath, reroot
+from ..remote import Remote
+
+
+def ref_option[FC: Callable[..., Any] | click.Command](**kwargs) -> Callable[[FC], FC]:  # type: ignore[name-defined]
+    return click.option(
+        "--ref",
+        "-R",
+        envvar=["DOCPUT_VERSION_REF", "FORGEJO_REF", "GITHUB_REF"],
+        show_envvar=True,
+        required=True,
+        **kwargs,
+    )
+
+
+@main_group.group(short_help="Create or edit versions.")
+def version_group(): ...
+
+
+@version_group.command(short_help="Push a documentation version to the remote.")
+@click.argument("source", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@remote_option(help="Remote to push to.")
+@ref_option(help="Version reference to push to.")
+@click.option(
+    "--latest",
+    "-l",
+    is_flag=True,
+    default=False,
+    help="Mark this version as the latest release.",
+)
+@click.option(
+    "--visible/--hidden",
+    "-v/-h",
+    default=None,
+    help="Show this version in the version menu on the site.",
+)
+@click.option(
+    "--url",
+    "-u",
+    envvar=["DOCPUT_VERSION_URL"],
+    show_envvar=True,
+    help="""
+         Subdirectory on the site to write and link to. If not provided when pushing a new version, use the version ref with any text matching regex in the
+         config value `version.url_strip` removed. By default, this removes "refs/" from the start of the reference, so a version with the reference
+         `refs/tags/v1.0.0` would be published to `tags/v1.0.0`
+         """,
+)
+@click.option(
+    "--name",
+    "-n",
+    envvar=["DOCPUT_VERSION_NAME", "FORGEJO_REF_NAME", "GITHUB_REF_NAME"],
+    show_envvar=True,
+    help="The name to display for this version in the version menu.",
+)
+def push(
+    source: Path,
+    remote: Remote,
+    ref: str,
+    latest: bool,
+    visible: bool | None,
+    url: str | None,
+    name: str | None,
+):
+    """
+    Push a documentation version from SOURCE to the remote.
+    """
+    config = get_config()
+    manifest = remote.manifest
+    if (version := manifest.versions.get(ref)) is None:
+        # version does not exist in the manifest, so we need to make sure some values get filled in
+        if url is None:
+            url = re.sub(config.get("url_strip_regex"), "", ref)
+        version = VersionRecord(ref, {})
+        manifest.versions[ref] = version
+
+    # remove any old deployed versions. Old href may not equal the new href
+    if version.url is not None:
+        remote.delete(version.url)
+
+    # update the version properties
+    if name is not None:
+        version.name = name
+    if url is not None:
+        version.url = url
+    if visible is not None:
+        version.visible = visible
+
+    # root of the version we are deploying to
+    if version.url is None:
+        raise ClickException(f"Version {ref} has no href and none was provided")
+    version_url = URLPath(version.url)
+    assert not version_url.is_absolute(), "version URL must be a relative path"
+
+    # write local version and symlink in the manifest
+    remote.write(source, version_url, overwrite=True)
+    remote.make_symlink(
+        URLPath("/") / config.get("manifest_url"),
+        reroot(URLPath("/", version_url), config.get("manifest_url")),
+    )
+
+    # if this is the latest, make a symlink from /latest
+    if latest:
+        manifest.latest = version
+        latest_url = URLPath(config.get("latest_url"))
+        assert not latest_url.is_absolute(), "latest URL must be a relative path"
+        remote.make_symlink(version_url, latest_url)
+
+
+@version_group.command()
+@remote_option(help="Remote to delete the version from.")
+@ref_option(help="Version reference to delete.")
+@click.option(
+    "--keep",
+    is_flag=True,
+    default=False,
+    help="Keep the corresponding documentation, just delete the manifest record.",
+)
+def delete(remote: Remote, ref, keep):
+    """Delete a version from the remote."""
+    manifest = remote.manifest
+    if (latest := manifest.latest) is not None and latest.ref == ref:
+        manifest.latest = None
+
+    if (version := manifest.versions.pop(ref)) is None:
+        raise ClickException(f"Version {ref} does not exist in the manifest")
+
+    if not keep and version.url is not None:
+        remote.delete(version.url)
+
+
+@version_group.command()
+@remote_option(help="Remote to list versions on.", commit_on_close=False)
+def list_command(remote: Remote):
+    """List all versions in the manifest."""
+    for version in remote.manifest.versions.values():
+        print(version)
+
+
+@version_group.command()
+@remote_option()
+@ref_option()
+@click.option(
+    "--visible/--hidden",
+    "-v/-h",
+    help="Show this version in the version menu on the site.",
+)
+@click.option(
+    "--url",
+    "-u",
+    envvar=["DOCPUT_VERSION_URL"],
+    show_envvar=True,
+    help="URL on the site to write and link to. Must be a relative-path reference.",
+)
+@click.option(
+    "--name",
+    "-n",
+    envvar=["DOCPUT_VERSION_NAME"],
+    show_envvar=True,
+    help="The name to display for this version in the version menu.",
+)
+def edit(
+    remote: Remote, ref: str, visible: bool | None, url: str | None, name: str | None
+):
+    """Edit a version in the manifest."""
+    if (version := remote.manifest.versions.get(ref)) is None:
+        raise ClickException(f"Version {ref} does not exist in the manifest")
+
+    if visible is not None:
+        version.visible = visible
+    if url is not None:
+        version.url = url
+    if name is not None:
+        version.name = name