hexdoc.cli.app

  1import code
  2import logging
  3import os
  4import shutil
  5import sys
  6from dataclasses import dataclass
  7from http.server import HTTPServer, SimpleHTTPRequestHandler
  8from pathlib import Path
  9from textwrap import dedent
 10from typing import Annotated, Any, Optional
 11
 12import typer
 13from packaging.version import Version
 14from typer import Argument, Option
 15from yarl import URL
 16
 17from hexdoc.__version__ import VERSION
 18from hexdoc.core import ModResourceLoader, ResourceLocation
 19from hexdoc.data.metadata import HexdocMetadata
 20from hexdoc.data.sitemap import (
 21    delete_updated_books,
 22    dump_sitemap,
 23    load_sitemap,
 24)
 25from hexdoc.graphics.render import BlockRenderer, DebugType
 26from hexdoc.jinja.render import create_jinja_env, get_templates, render_book
 27from hexdoc.minecraft import I18n
 28from hexdoc.minecraft.assets import (
 29    AnimatedTexture,
 30    PNGTexture,
 31    TextureContext,
 32)
 33from hexdoc.minecraft.assets.load_assets import render_block
 34from hexdoc.minecraft.models.item import ItemModel
 35from hexdoc.minecraft.models.load import load_model
 36from hexdoc.patchouli import BookContext, FormattingContext
 37from hexdoc.plugin import ModPluginWithBook
 38from hexdoc.utils import git_root, setup_logging, write_to_path
 39from hexdoc.utils.logging import repl_readfunc
 40
 41from . import ci
 42from .utils.args import (
 43    DEFAULT_MERGE_DST,
 44    DEFAULT_MERGE_SRC,
 45    BranchOption,
 46    DefaultTyper,
 47    PathArgument,
 48    PropsOption,
 49    ReleaseOption,
 50    VerbosityOption,
 51)
 52from .utils.load import (
 53    init_context,
 54    load_common_data,
 55    render_textures_and_export_metadata,
 56)
 57
 58logger = logging.getLogger(__name__)
 59
 60
 61def set_default_env():
 62    """Sets placeholder values for unneeded environment variables."""
 63    for key, value in {
 64        "GITHUB_REPOSITORY": "placeholder/placeholder",
 65        "GITHUB_SHA": "",
 66        "GITHUB_PAGES_URL": "",
 67    }.items():
 68        os.environ.setdefault(key, value)
 69
 70
 71@dataclass(kw_only=True)
 72class LoadedBookInfo:
 73    language: str
 74    i18n: I18n
 75    context: dict[str, Any]
 76    book_id: ResourceLocation
 77    book: Any
 78
 79
 80app = DefaultTyper()
 81app.add_typer(ci.app)
 82
 83
 84def version_callback(value: bool):
 85    if value:
 86        print(f"hexdoc {VERSION}")
 87        raise typer.Exit()
 88
 89
 90@app.callback()
 91def callback(
 92    verbosity: VerbosityOption = 0,
 93    quiet_lang: Optional[list[str]] = None,
 94    version: Annotated[
 95        bool,
 96        Option("--version", "-V", callback=version_callback, is_eager=True),
 97    ] = False,
 98):
 99    if quiet_lang:
100        logger.warning(
101            "`--quiet-lang` is deprecated, use `props.lang.{lang}.quiet` instead."
102        )
103    setup_logging(verbosity, ci=False, quiet_langs=quiet_lang)
104
105
106@app.command()
107def repl(*, props_file: PropsOption):
108    """Start a Python shell with some helpful extra locals added from hexdoc."""
109
110    repl_locals = dict[str, Any](
111        props_path=props_file,
112    )
113
114    try:
115        props, pm, book_plugin, plugin = load_common_data(props_file, branch="")
116        repl_locals |= dict(
117            props=props,
118            pm=pm,
119            plugin=plugin,
120        )
121
122        loader = ModResourceLoader.load_all(
123            props,
124            pm,
125            export=False,
126        )
127        repl_locals["loader"] = loader
128
129        if props.book_id:
130            book_id, book_data = book_plugin.load_book_data(props.book_id, loader)
131        else:
132            book_id = None
133            book_data = {}
134
135        i18n = I18n.load_all(
136            loader,
137            enabled=book_plugin.is_i18n_enabled(book_data),
138        )[props.default_lang]
139
140        all_metadata = loader.load_metadata(model_type=HexdocMetadata)
141        repl_locals["all_metadata"] = all_metadata
142
143        if book_id and book_data:
144            context = init_context(
145                book_id=book_id,
146                book_data=book_data,
147                pm=pm,
148                loader=loader,
149                i18n=i18n,
150                all_metadata=all_metadata,
151            )
152            book = book_plugin.validate_book(book_data, context=context)
153            repl_locals |= dict(
154                book=book,
155                context=context,
156            )
157    except Exception as e:
158        print(e)
159
160    code.interact(
161        banner=dedent(
162            f"""\
163            [hexdoc repl] Python {sys.version}
164            Locals: {', '.join(sorted(repl_locals.keys()))}"""
165        ),
166        readfunc=repl_readfunc(),
167        local=repl_locals,
168        exitmsg="",
169    )
170
171
172@app.command()
173def build(
174    output_dir: PathArgument = DEFAULT_MERGE_SRC,
175    *,
176    branch: BranchOption,
177    release: ReleaseOption = False,
178    clean: bool = False,
179    props_file: PropsOption,
180) -> Path:
181    """Export resources and render the web book.
182
183    For developers: returns the site path (eg. `/v/latest/main`).
184    """
185
186    props, pm, book_plugin, plugin = load_common_data(props_file, branch)
187
188    if props.env.hexdoc_subdirectory:
189        output_dir /= props.env.hexdoc_subdirectory
190
191    logger.info("Exporting resources.")
192    with ModResourceLoader.clean_and_load_all(props, pm, export=True) as loader:
193        site_path = plugin.site_path(versioned=release)
194        site_dir = output_dir / site_path
195
196        asset_loader = plugin.asset_loader(
197            loader=loader,
198            site_url=props.env.github_pages_url.joinpath(*site_path.parts),
199            asset_url=props.env.asset_url,
200            render_dir=site_dir,
201        )
202
203        all_metadata = render_textures_and_export_metadata(loader, asset_loader)
204
205        if not props.book_id:
206            logger.info("Skipping book load because props.book_id is not set.")
207            return site_dir
208
209        book_id, book_data = book_plugin.load_book_data(props.book_id, loader)
210
211        all_i18n = I18n.load_all(
212            loader,
213            enabled=book_plugin.is_i18n_enabled(book_data),
214        )
215
216        logger.info("Loading books for all languages.")
217        books = list[LoadedBookInfo]()
218        for language, i18n in all_i18n.items():
219            try:
220                context = init_context(
221                    book_id=book_id,
222                    book_data=book_data,
223                    pm=pm,
224                    loader=loader,
225                    i18n=i18n,
226                    all_metadata=all_metadata,
227                )
228                book = book_plugin.validate_book(book_data, context=context)
229                books.append(
230                    LoadedBookInfo(
231                        language=language,
232                        i18n=i18n,
233                        context=context,
234                        book_id=book_id,
235                        book=book,
236                    )
237                )
238            except Exception:
239                if not props.lang[language].ignore_errors:
240                    raise
241                logger.exception(f"Failed to load book for {language}")
242
243        if not props.template:
244            logger.info("Skipping book render because props.template is not set.")
245            return site_dir
246
247        if not isinstance(plugin, ModPluginWithBook):
248            raise ValueError(
249                f"ModPlugin registered for modid `{props.modid}` (from props.modid)"
250                f" does not inherit from ModPluginWithBook: {plugin}"
251            )
252
253        logger.info("Setting up Jinja template environment.")
254        env = create_jinja_env(pm, props.template.include, props_file)
255
256        logger.info(f"Rendering book for {len(books)} language(s).")
257        for book_info in books:
258            try:
259                templates = get_templates(
260                    props=props,
261                    pm=pm,
262                    book=book_info.book,
263                    context=book_info.context,
264                    env=env,
265                )
266                if not templates:
267                    raise RuntimeError(
268                        "No templates to render, check your props.template configuration "
269                        f"(in {props_file.as_posix()})"
270                    )
271
272                book_ctx = BookContext.of(book_info.context)
273                formatting_ctx = FormattingContext.of(book_info.context)
274                texture_ctx = TextureContext.of(book_info.context)
275
276                site_book_path = plugin.site_book_path(
277                    book_info.language,
278                    versioned=release,
279                )
280                if clean:
281                    shutil.rmtree(output_dir / site_book_path, ignore_errors=True)
282
283                template_args: dict[str, Any] = book_info.context | {
284                    "all_metadata": all_metadata,
285                    "png_textures": PNGTexture.get_lookup(texture_ctx.textures),
286                    "animations": sorted(  # this MUST be sorted to avoid flaky tests
287                        AnimatedTexture.get_lookup(texture_ctx.textures).values(),
288                        key=lambda t: t.css_class,
289                    ),
290                    "book": book_info.book,
291                    "book_links": book_ctx.book_links,
292                }
293
294                render_book(
295                    props=props,
296                    pm=pm,
297                    plugin=plugin,
298                    lang=book_info.language,
299                    book_id=book_info.book_id,
300                    i18n=book_info.i18n,
301                    macros=formatting_ctx.macros,
302                    env=env,
303                    templates=templates,
304                    output_dir=output_dir,
305                    version=plugin.mod_version if release else f"latest/{branch}",
306                    site_path=site_book_path,
307                    versioned=release,
308                    template_args=template_args,
309                )
310            except Exception:
311                if not props.lang[book_info.language].ignore_errors:
312                    raise
313                logger.exception(f"Failed to render book for {book_info.language}")
314
315    logger.info("Done.")
316    return site_dir
317
318
319@app.command()
320def merge(
321    *,
322    props_file: PropsOption,
323    src: Path = DEFAULT_MERGE_SRC,
324    dst: Path = DEFAULT_MERGE_DST,
325    release: ReleaseOption = False,
326):
327    props, _, _, plugin = load_common_data(props_file, branch="", book=True)
328    if not props.template:
329        raise ValueError("Expected a value for props.template, got None")
330
331    if props.env.hexdoc_subdirectory:
332        src /= props.env.hexdoc_subdirectory
333        dst /= props.env.hexdoc_subdirectory
334
335    dst.mkdir(parents=True, exist_ok=True)
336
337    # remove any stale data that we're about to replace
338    delete_updated_books(src=src, dst=dst, release=release)
339
340    # do the merge
341    shutil.copytree(src=src, dst=dst, dirs_exist_ok=True)
342
343    # rebuild the sitemap
344    sitemap, minecraft_sitemap = load_sitemap(dst)
345    dump_sitemap(dst, sitemap, minecraft_sitemap)
346
347    # find paths for redirect pages
348    redirects = dict[Path, str]()
349
350    root_version: Version | None = None
351    root_redirect: str | None = None
352
353    for version, item in sitemap.items():
354        if version.startswith("latest"):  # TODO: check type of item instead
355            continue
356
357        redirects[plugin.site_root / version] = item.default_marker.redirect_contents
358        for lang, marker in item.markers.items():
359            redirects[plugin.site_root / version / lang] = marker.redirect_contents
360
361        item_version = Version(version)
362        if not root_version or item_version > root_version:
363            root_version = item_version
364            root_redirect = item.default_marker.redirect_contents
365
366    if root_redirect is None:
367        # TODO: use plugin to build this path
368        # TODO: refactor
369        if item := sitemap.get(f"latest/{props.default_branch}"):
370            root_redirect = item.default_marker.redirect_contents
371        elif sitemap:
372            key = sorted(sitemap.keys())[0]
373            root_redirect = sitemap[key].default_marker.redirect_contents
374            logger.warning(
375                f"No book exists for the default branch `{props.default_branch}`, generating root redirect to `{key}` (check the value of `default_branch` in hexdoc.toml)"
376            )
377        else:
378            logger.error("No books found, skipping root redirect")
379
380    if root_redirect is not None:
381        redirects[Path()] = root_redirect
382
383    # write redirect pages
384    if props.template.redirect:
385        filename, _ = props.template.redirect
386        for path, redirect_contents in redirects.items():
387            write_to_path(dst / path / filename, redirect_contents)
388
389    # bypass Jekyll on GitHub Pages
390    (dst / ".nojekyll").touch()
391
392
393@app.command()
394def serve(
395    *,
396    props_file: PropsOption,
397    port: int = 8000,
398    src: Path = DEFAULT_MERGE_SRC,
399    dst: Path = DEFAULT_MERGE_DST,
400    branch: BranchOption,
401    release: bool = True,
402    clean: bool = False,
403    do_merge: Annotated[bool, Option("--merge/--no-merge")] = True,
404):
405    book_root = dst
406    relative_root = book_root.resolve().relative_to(Path.cwd())
407
408    base_url = URL.build(scheme="http", host="localhost", port=port)
409    book_url = base_url.joinpath(*relative_root.parts)
410
411    repo_root = git_root(props_file.parent)
412    asset_root = repo_root.relative_to(Path.cwd())
413
414    os.environ |= {
415        # prepend a slash to the path so it can find the texture in the local repo
416        # eg. http://localhost:8000/_site/src/docs/Common/...
417        # vs. http://localhost:8000/Common/...
418        "DEBUG_GITHUBUSERCONTENT": str(base_url.joinpath(*asset_root.parts)),
419        "GITHUB_PAGES_URL": str(book_url),
420    }
421
422    print()
423    logger.info(f"hexdoc build --{'' if release else 'no-'}release")
424    build(
425        branch=branch,
426        props_file=props_file,
427        output_dir=src,
428        release=True,
429        clean=clean,
430    )
431
432    if do_merge:
433        print()
434        logger.info("hexdoc merge")
435        merge(
436            src=src,
437            dst=dst,
438            props_file=props_file,
439        )
440
441    print()
442    logger.info(f"Serving web book at {book_url} (press ctrl+c to exit)\n")
443    with HTTPServer(("", port), SimpleHTTPRequestHandler) as httpd:
444        # ignore KeyboardInterrupt to stop Typer from printing "Aborted."
445        # because it keeps printing after nodemon exits and breaking the output
446        try:
447            httpd.serve_forever()
448        except KeyboardInterrupt:
449            pass
450
451
452@app.command()
453def render_model(
454    model_id: str,
455    *,
456    props_file: PropsOption,
457    output_path: Annotated[Path, Option("--output", "-o")] = Path("out.png"),
458    axes: bool = False,
459    normals: bool = False,
460):
461    """Use hexdoc's block rendering to render an item or block model."""
462    set_default_env()
463    props, pm, *_ = load_common_data(props_file, branch="")
464
465    debug = DebugType.NONE
466    if axes:
467        debug |= DebugType.AXES
468    if normals:
469        debug |= DebugType.NORMALS
470
471    with ModResourceLoader.load_all(props, pm, export=False) as loader:
472        _, model = load_model(loader, ResourceLocation.from_str(model_id))
473        while isinstance(model, ItemModel) and model.parent:
474            _, model = load_model(loader, model.parent)
475
476        if isinstance(model, ItemModel):
477            raise ValueError(f"Invalid block id: {model_id}")
478
479        with BlockRenderer(loader=loader, debug=debug) as renderer:
480            renderer.render_block_model(model, output_path)
481
482
483@app.command()
484def render_models(
485    model_ids: Annotated[Optional[list[str]], Argument()] = None,
486    *,
487    props_file: PropsOption,
488    render_all: Annotated[bool, Option("--all")] = False,
489    output_dir: Annotated[Path, Option("--output", "-o")] = Path("out"),
490    site_url_str: Annotated[Optional[str], Option("--site-url")] = None,
491    export_resources: bool = True,
492):
493    if not (model_ids or render_all):
494        raise ValueError("At least one model id must be provided if --all is missing")
495
496    site_url = URL(site_url_str or "")
497
498    set_default_env()
499    props, pm, _, plugin = load_common_data(props_file, branch="")
500
501    with ModResourceLoader.load_all(props, pm, export=export_resources) as loader:
502        if model_ids:
503            with BlockRenderer(loader=loader, output_dir=output_dir) as renderer:
504                for model_id in model_ids:
505                    model_id = ResourceLocation.from_str(model_id)
506                    render_block(model_id, renderer, site_url)
507        else:
508            asset_loader = plugin.asset_loader(
509                loader=loader,
510                site_url=site_url,
511                asset_url=props.env.asset_url,
512                render_dir=output_dir,
513            )
514            render_textures_and_export_metadata(loader, asset_loader)
515
516    logger.info("Done.")
517
518
519@app.command(deprecated=True)
520def export(
521    output_dir: PathArgument = DEFAULT_MERGE_SRC,
522    *,
523    branch: BranchOption,
524    release: ReleaseOption = False,
525    props_file: PropsOption,
526):
527    logger.warning("This command is deprecated, use `hexdoc build` instead.")
528    build(
529        output_dir,
530        branch=branch,
531        release=release,
532        props_file=props_file,
533    )
534
535
536@app.command(deprecated=True)
537def render(
538    output_dir: PathArgument = DEFAULT_MERGE_SRC,
539    *,
540    branch: BranchOption,
541    release: ReleaseOption = False,
542    clean: bool = False,
543    lang: Optional[str] = None,
544    props_file: PropsOption,
545):
546    logger.warning("This command is deprecated, use `hexdoc build` instead.")
547    if lang is not None:
548        logger.warning(
549            "`--lang` is deprecated and has been removed from `hexdoc build`."
550        )
551    build(
552        output_dir,
553        branch=branch,
554        release=release,
555        clean=clean,
556        props_file=props_file,
557    )
558
559
560if __name__ == "__main__":
561    app()