hexdoc.cli.ci

  1"""
  2Commands designed to run in a GitHub Actions workflow.
  3"""
  4
  5# pyright: reportPrivateUsage=false
  6
  7import os
  8import shutil
  9import subprocess
 10from functools import cached_property
 11from pathlib import Path
 12from typing import Literal, TypedDict, TypeVar, Unpack
 13
 14from github import Auth, Github, UnknownObjectException
 15from github.Repository import Repository
 16from pydantic import TypeAdapter
 17from typer import Typer
 18
 19from hexdoc.cli.utils.args import PropsOption, ReleaseOption
 20from hexdoc.model import HexdocModel, HexdocSettings
 21from hexdoc.utils import setup_logging
 22
 23app = Typer(name="ci")
 24
 25
 26@app.command()
 27def build(
 28    *,
 29    props_file: PropsOption,
 30    release: ReleaseOption,
 31    run_hatch_build: bool = True,
 32):
 33    from . import app as hexdoc_app
 34
 35    env = CIEnvironment.model_getenv()
 36    setup_logging(env.verbosity, ci=True)
 37
 38    # FIXME: scuffed. why are we setting environment variables here :/
 39    for key in [
 40        "MOCK_GITHUB_PAGES_URL",  # highest priority so tests work correctly
 41        "HEXDOC_SITE_URL",  # TODO: this should be supported in more places
 42        "GITHUB_PAGES_URL",
 43    ]:
 44        if pages_url := os.getenv(key):
 45            break
 46    else:
 47        pages_url = get_pages_url(env.repo)
 48    os.environ["GITHUB_PAGES_URL"] = pages_url
 49
 50    site_path = hexdoc_app.build(
 51        Path("_site/src/docs"),
 52        clean=True,
 53        branch=env.branch,
 54        props_file=props_file,
 55        release=release,
 56    )
 57
 58    if run_hatch_build:
 59        site_dist = site_path / "dist"
 60        if site_dist.is_dir():
 61            shutil.rmtree(site_dist)
 62
 63        subprocess.run(["hatch", "build", "--clean"], check=True)
 64        shutil.copytree("dist", site_dist)
 65
 66    env.set_output("pages-url", pages_url)
 67
 68
 69@app.command()
 70def merge(
 71    *,
 72    props_file: PropsOption,
 73    release: ReleaseOption,
 74):
 75    from . import app as hexdoc_app
 76
 77    env = CIEnvironment.model_getenv()
 78    setup_logging(env.verbosity, ci=True)
 79    hexdoc_app.merge(props_file=props_file, release=release)
 80
 81
 82@app.command(deprecated=True)
 83def export(
 84    *,
 85    props_file: PropsOption,
 86    release: ReleaseOption,
 87):
 88    build(props_file=props_file, release=release)
 89
 90
 91@app.command(deprecated=True)
 92def render(
 93    lang: str,
 94    *,
 95    props_file: PropsOption,
 96    release: ReleaseOption,
 97):
 98    build(props_file=props_file, release=release)
 99
100
101# utils
102
103_T = TypeVar("_T")
104
105
106class CIEnvironment(HexdocSettings):
107    github_output: str
108    github_ref_name: str
109    github_repository: str
110    github_token: str | None = None
111    runner_debug: bool = False
112
113    @property
114    def branch(self):
115        return self.github_ref_name
116
117    @property
118    def verbosity(self):
119        return 1 if self.runner_debug else 0
120
121    @cached_property
122    def repo(self):
123        return self.gh.get_repo(self.github_repository)
124
125    @cached_property
126    def gh(self):
127        return Github(
128            auth=self._gh_auth,
129        )
130
131    @property
132    def _gh_auth(self):
133        if self.github_token:
134            return Auth.Token(self.github_token)
135
136    def set_output(self, name: str, value: str | tuple[type[_T], _T]):
137        match value:
138            case str():
139                pass
140            case (data_type, data):
141                ta = TypeAdapter(data_type)
142                value = ta.dump_json(data).decode()
143
144        with open(self.github_output, "a") as f:
145            print(f"{name}={value}", file=f)
146
147
148def get_pages_url(repo: Repository) -> str:
149    endpoint = f"{repo.url}/pages"
150    try:
151        _, data = repo._requester.requestJsonAndCheck("GET", endpoint)
152    except Exception as e:
153        e.add_note(f"  Endpoint: {endpoint}")
154        if isinstance(e, UnknownObjectException):
155            e.add_note(
156                "Note: check if GitHub Pages is enabled in this repo"
157                + " (https://hexdoc.hexxy.media/docs/guides/deployment/github-pages)"
158            )
159        raise
160    return str(data["html_url"])
161
162
163class CIMatrixItem(HexdocModel):
164    value: str
165    continue_on_error: bool
166
167
168class AnnotationKwargs(TypedDict, total=False):
169    title: str
170    """Custom title"""
171    file: str
172    """Filename"""
173    col: int
174    """Column number, starting at 1"""
175    endColumn: int
176    """End column number"""
177    line: int
178    """Line number, starting at 1"""
179    endLine: int
180    """End line number"""
181
182
183def add_notice(message: str, **kwargs: Unpack[AnnotationKwargs]):
184    return add_annotation("notice", message, **kwargs)
185
186
187def add_warning(message: str, **kwargs: Unpack[AnnotationKwargs]):
188    return add_annotation("warning", message, **kwargs)
189
190
191def add_error(message: str, **kwargs: Unpack[AnnotationKwargs]):
192    return add_annotation("error", message, **kwargs)
193
194
195def add_annotation(
196    type: Literal["notice", "warning", "error"],
197    message: str,
198    **kwargs: Unpack[AnnotationKwargs],
199):
200    if kwargs:
201        kwargs_str = " " + ",".join(f"{k}={v}" for k, v in kwargs.items())
202    else:
203        kwargs_str = ""
204
205    print(f"::{type}{kwargs_str}::{message}")