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