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