celshast 0.0.1__py3-none-any.whl

celshast/__init__.py

@@ -0,0 +1,377 @@
+"""A Farama Foundation Sphinx documentation theme based on Furo."""
+
+__version__ = "0.0.1"
+
+import hashlib
+import logging
+import os
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Dict, Iterator, List, Optional
+
+import sphinx.application
+from docutils import nodes
+from pygments.formatters import HtmlFormatter
+from pygments.style import Style
+from pygments.token import Text
+from sphinx.builders.html import StandaloneHTMLBuilder
+from sphinx.environment.adapters.toctree import TocTree
+from sphinx.errors import ConfigError
+from sphinx.highlighting import PygmentsBridge
+from sphinx.transforms.post_transforms import SphinxPostTransform
+
+from .farama_directives import FaramaProjectHeadingDirective, FaramaProjectLogoDirective
+from .navigation import get_navigation_tree
+
+THEME_PATH = (Path(__file__).parent / "theme" / "celshast").resolve()
+
+logger = logging.getLogger(__name__)
+
+# GLOBAL STATE
+_KNOWN_STYLES_IN_USE: Dict[str, Optional[Style]] = {
+    "light": None,
+    "dark": None,
+}
+
+
+class WrapTableAndMathInAContainerTransform(SphinxPostTransform):
+    """A Sphinx post-transform that wraps `table` and `div.math` in a container `div`.
+
+    This makes it possible to handle these overflowing the content-width, which is
+    necessary in a responsive theme.
+    """
+
+    formats = ("html",)
+    default_priority = 500
+
+    def run(self, **kwargs: Any) -> None:
+        """Perform the post-transform on `self.document`."""
+        get_nodes = (
+            self.document.findall  # docutils 0.18+
+            if hasattr(self.document, "findall")
+            else self.document.traverse  # docutils <= 0.17.x
+        )
+        for node in list(get_nodes(nodes.table)):
+            new_node = nodes.container(classes=["table-wrapper"])
+            new_node.update_all_atts(node)
+            node.parent.replace(node, new_node)
+            new_node.append(node)
+
+        for node in list(get_nodes(nodes.math_block)):
+            new_node = nodes.container(classes=["math-wrapper"])
+            new_node.update_all_atts(node)
+            node.parent.replace(node, new_node)
+            new_node.append(node)
+
+
+def has_not_enough_items_to_show_toc(
+    builder: StandaloneHTMLBuilder, docname: str
+) -> bool:
+    """Check if the toc has one or fewer items."""
+    assert builder.env
+
+    toctree = TocTree(builder.env).get_toc_for(docname, builder)
+    try:
+        self_toctree = toctree[0][1]
+    except IndexError:
+        val = True
+    else:
+        # There's only the page's own toctree in there.
+        val = len(self_toctree) == 1 and self_toctree[0].tagname == "toctree"
+    return val
+
+
+def get_pygments_style_colors(
+    style: Style, *, fallbacks: Dict[str, str]
+) -> Dict[str, str]:
+    """Get background/foreground colors for given pygments style."""
+    background = style.background_color
+    text_colors = style.style_for_token(Text)
+    foreground = text_colors["color"]
+
+    if not background:
+        background = fallbacks["background"]
+
+    if not foreground:
+        foreground = fallbacks["foreground"]
+    else:
+        foreground = f"#{foreground}"
+
+    return {"background": background, "foreground": foreground}
+
+
+@lru_cache(maxsize=2)
+def get_colors_for_codeblocks(
+    highlighter: PygmentsBridge, *, fg: str, bg: str
+) -> Dict[str, str]:
+    """Get background/foreground colors for given pygments style."""
+    return get_pygments_style_colors(
+        highlighter.formatter_args["style"],
+        fallbacks={
+            "foreground": fg,
+            "background": bg,
+        },
+    )
+
+
+def _compute_navigation_tree(context: Dict[str, Any]) -> str:
+    # The navigation tree, generated from the sphinx-provided ToC tree.
+    if "toctree" in context:
+        toctree = context["toctree"]
+        toctree_html = toctree(
+            collapse=False,
+            titles_only=True,
+            maxdepth=-1,
+            includehidden=True,
+        )
+    else:
+        toctree_html = ""
+
+    return get_navigation_tree(toctree_html)
+
+
+def _compute_hide_toc(
+    context: Dict[str, Any],
+    *,
+    builder: StandaloneHTMLBuilder,
+    docname: str,
+) -> bool:
+    # Should the table of contents be hidden?
+    file_meta = context.get("meta", None) or {}
+    if "hide-toc" in file_meta:
+        return True
+    elif "toc" not in context:
+        return True
+    elif not context["toc"]:
+        return True
+
+    return has_not_enough_items_to_show_toc(builder, docname)
+
+
+@lru_cache(maxsize=None)
+def _asset_hash(path: str) -> str:
+    """Append a `?digest=` to an url based on the file content."""
+    full_path = THEME_PATH / "static" / path
+    digest = hashlib.sha1(full_path.read_bytes()).hexdigest()
+
+    return f"_static/{path}?digest={digest}"
+
+
+def _add_asset_hashes(static: List[str], add_digest_to: List[str]) -> None:
+    if sphinx.version_info >= (7, 1):
+        # https://github.com/sphinx-doc/sphinx/pull/11415 added the relevant
+        # functionality to Sphinx, so we don't need to do anything.
+        return
+
+    for asset in add_digest_to:
+        index = static.index("_static/" + asset)
+        static[index].filename = _asset_hash(asset)  # type: ignore
+
+
+def _html_page_context(
+    app: sphinx.application.Sphinx,
+    pagename: str,
+    templatename: str,
+    context: Dict[str, Any],
+    doctree: Any,
+) -> None:
+    if "css_files" in context:
+        if "_static/styles/celshast.css" not in [
+            c.filename.split("?")[0] for c in context["css_files"]
+        ]:
+            raise ConfigError(
+                "This documentation is not using `celshast.css` as the stylesheet. "
+                "If you have set `html_style` in your conf.py file, remove it."
+            )
+
+        _add_asset_hashes(
+            context["css_files"],
+            ["styles/celshast.css", "styles/celshast-extensions.css"],
+        )
+    if "scripts" in context:
+        _add_asset_hashes(
+            context["scripts"],
+            ["scripts/celshast.js"],
+        )
+
+    # Basic constants
+    context["celshast_version"] = __version__
+
+    # Values computed from page-level context.
+    context["celshast_navigation_tree"] = _compute_navigation_tree(context)
+    context["celshast_hide_toc"] = _compute_hide_toc(
+        context, builder=app.builder, docname=pagename
+    )
+
+    # Inject information about styles
+    context["celshast_pygments"] = {
+        "light": get_pygments_style_colors(
+            _KNOWN_STYLES_IN_USE["light"],
+            fallbacks=dict(
+                foreground="black",
+                background="white",
+            ),
+        ),
+        "dark": get_pygments_style_colors(
+            _KNOWN_STYLES_IN_USE["dark"],
+            fallbacks=dict(
+                foreground="white",
+                background="black",
+            ),
+        ),
+    }
+
+    # Base url
+    context["html_baseurl"] = app.config.html_baseurl
+
+    # Projects Menu
+    context["farama_projects_api"] = "https://farama.org/api/projects.json"
+
+
+def _builder_inited(app: sphinx.application.Sphinx) -> None:
+    if "celshast" in app.config.extensions:
+        raise ConfigError(
+            "Did you list 'celshast' in the `extensions` in conf.py? "
+            "If so, please remove it. Celshast does not work with non-HTML builders "
+            "and specifying it as an `html_theme` is sufficient."
+        )
+
+    if not isinstance(app.builder, StandaloneHTMLBuilder) or app.builder.name not in {
+        "html",
+        "dirhtml",
+    }:
+        raise ConfigError(
+            "Celshast is being used as an extension in a non-HTML build. "
+            "This should not happen."
+        )
+
+    # Our JS file needs to be loaded as soon as possible.
+    app.add_js_file("scripts/celshast.js", priority=200)
+
+    # 500 is the default priority for extensions, we want this after this.
+    app.add_css_file("styles/celshast-extensions.css", priority=600)
+
+    # Add custom directives
+    app.add_directive("project-logo", FaramaProjectLogoDirective)
+    app.add_directive("project-heading", FaramaProjectHeadingDirective)
+
+    builder = app.builder
+    assert (
+        builder.highlighter is not None
+    ), "there should be a default style known to Sphinx"
+    assert (
+        builder.dark_highlighter is None
+    ), "this shouldn't be a dark style known to Sphinx"
+    update_known_styles_state(app)
+
+    def _update_default(key: str, *, new_default: Any) -> None:
+        app.config.values[key] = (new_default, *app.config.values[key][1:])
+
+    # Change the default permalinks icon
+    _update_default("html_permalinks_icon", new_default="#")
+
+
+def update_known_styles_state(app: sphinx.application.Sphinx) -> None:
+    """Update a global store of known styles of this application."""
+    global _KNOWN_STYLES_IN_USE
+
+    _KNOWN_STYLES_IN_USE = {
+        "light": _get_light_style(app),
+        "dark": _get_dark_style(app),
+    }
+
+
+def _get_light_style(app: sphinx.application.Sphinx) -> Style:
+    return app.builder.highlighter.formatter_args["style"]
+
+
+def _get_dark_style(app: sphinx.application.Sphinx) -> Style:
+    dark_style = app.config.pygments_dark_style
+    return PygmentsBridge("html", dark_style).formatter_args["style"]
+
+
+def _get_styles(formatter: HtmlFormatter, *, prefix: str) -> Iterator[str]:
+    """Get styles out of a formatter, where everything has the correct prefix."""
+    for line in formatter.get_linenos_style_defs():
+        yield f"{prefix} {line}"
+    yield from formatter.get_background_style_defs(prefix)
+    yield from formatter.get_token_style_defs(prefix)
+
+
+def get_pygments_stylesheet() -> str:
+    """Generate the theme-specific pygments.css.
+
+    There is no way to tell Sphinx how the theme handles dark mode; at this time.
+    """
+    light_formatter = PygmentsBridge.html_formatter(style=_KNOWN_STYLES_IN_USE["light"])
+    dark_formatter = PygmentsBridge.html_formatter(style=_KNOWN_STYLES_IN_USE["dark"])
+
+    lines: List[str] = []
+
+    lines.extend(_get_styles(light_formatter, prefix=".highlight"))
+
+    lines.append("@media not print {")
+
+    dark_prefix = 'body[data-theme="dark"] .highlight'
+    lines.extend(_get_styles(dark_formatter, prefix=dark_prefix))
+
+    not_light_prefix = 'body:not([data-theme="light"]) .highlight'
+    lines.append("@media (prefers-color-scheme: dark) {")
+    lines.extend(_get_styles(dark_formatter, prefix=not_light_prefix))
+    lines.append("}")
+
+    lines.append("}")
+
+    return "\n".join(lines)
+
+
+# Yup, we overwrite the default pygments.css file, because it can't possibly respect
+# the needs of this theme.
+def _overwrite_pygments_css(
+    app: sphinx.application.Sphinx,
+    exception: Optional[Exception],
+) -> None:
+    if exception is not None:
+        return
+
+    assert app.builder
+    with open(
+        os.path.join(app.builder.outdir, "_static", "pygments.css"),
+        "w",
+        encoding="utf-8",
+    ) as f:
+        f.write(get_pygments_stylesheet())
+
+
+def setup(app: sphinx.application.Sphinx) -> Dict[str, Any]:
+    """Entry point for sphinx theming."""
+    app.require_sphinx("6.0")
+
+    app.add_config_value(
+        "pygments_dark_style", default="native", rebuild="env", types=[str]
+    )
+
+    # Add default MyST extensions
+    if "myst_enable_extensions" in app.config:
+        if isinstance(app.config.myst_enable_extensions, list):
+            app.config.myst_enable_extensions.append("dollarmath")
+        elif isinstance(app.config.myst_enable_extensions, set):
+            app.config.myst_enable_extensions.add("dollarmath")
+        else:
+            raise ConfigError(
+                "myst_enable_extensions should be a list or set of strings."
+            )
+
+    app.add_html_theme("celshast", str(THEME_PATH))
+
+    app.add_post_transform(WrapTableAndMathInAContainerTransform)
+
+    app.connect("html-page-context", _html_page_context)
+    app.connect("builder-inited", _builder_inited)
+    app.connect("build-finished", _overwrite_pygments_css)
+
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+        "version": __version__,
+    }

celshast/_demo_module.py

@@ -0,0 +1,54 @@
+# Copyright (c) 2021 Pradyun Gedam
+# Licensed under the Open Software License version 3.0
+# SPDX-License-Identifier: OSL-3.0
+
+"""This is a demo module included in the docs in order to exercise autodoc."""
+
+from typing import Optional, TextIO, Type, Union
+
+
+def show_warning(
+    message: Union[Warning, str],
+    category: Type[Warning],
+    filename: str,
+    lineno: int,
+    file: Optional[TextIO] = None,
+    line: Optional[str] = None,
+) -> None:
+    """Show a warning to the end user.
+
+    .. code:: python
+
+        warnings.showwarning = show_warning
+
+    :param message: What you want to tell the user.
+    :param category: The type of warning.
+    :param filename: The file that the warning is for.
+    :param lineno: The line that the warning is for.
+    :param file: Where to write the warning.
+    :param line: line of source code to be included in the warning message
+    """
+
+
+class RandomNumberGenerator:
+    """A random number generator."""
+
+    def __init__(self, *, seed: int = 4) -> None:
+        """Initialize."""
+        self._seed = 4
+
+    @property
+    def seed(self) -> int:
+        """Get seed for random number generation.
+
+        .. seealso:: https://xkcd.com/221/
+        """
+        return self._seed
+
+    def get_random_integer(self) -> int:
+        """Return a random integer."""
+        return self.seed
+
+    def get_random_float(self) -> float:
+        """Return a random float."""
+        return float(self.seed)

celshast/assets/scripts/celshast.js

@@ -0,0 +1,175 @@
+import Gumshoe from "./gumshoe-patched.js";
+
+////////////////////////////////////////////////////////////////////////////////
+// Scroll Handling
+////////////////////////////////////////////////////////////////////////////////
+var tocScroll = null;
+var header = null;
+var lastScrollTop = window.pageYOffset || document.documentElement.scrollTop;
+const GO_TO_TOP_OFFSET = 64;
+
+// function scrollHandlerForHeader() {
+//   if (Math.floor(header.getBoundingClientRect().top) == 0) {
+//     header.classList.add("scrolled");
+//   } else {
+//     header.classList.remove("scrolled");
+//   }
+// }
+
+function scrollHandlerForBackToTop(positionY) {
+  if (positionY < GO_TO_TOP_OFFSET) {
+    document.documentElement.classList.remove("show-back-to-top");
+  } else {
+    if (positionY < lastScrollTop) {
+      document.documentElement.classList.add("show-back-to-top");
+    } else if (positionY > lastScrollTop) {
+      document.documentElement.classList.remove("show-back-to-top");
+    }
+  }
+  lastScrollTop = positionY;
+}
+
+function scrollHandlerForTOC(positionY) {
+  if (tocScroll === null) {
+    return;
+  }
+
+  // top of page.
+  if (positionY == 0) {
+    tocScroll.scrollTo(0, 0);
+  } else if (
+    // bottom of page.
+    Math.ceil(positionY) >=
+    Math.floor(document.documentElement.scrollHeight - window.innerHeight)
+  ) {
+    tocScroll.scrollTo(0, tocScroll.scrollHeight);
+  } else {
+    // somewhere in the middle.
+    const current = document.querySelector(".scroll-current");
+    if (current == null) {
+      return;
+    }
+
+    // https://github.com/pypa/pip/issues/9159 This breaks scroll behaviours.
+    // // scroll the currently "active" heading in toc, into view.
+    // const rect = current.getBoundingClientRect();
+    // if (0 > rect.top) {
+    //   current.scrollIntoView(true); // the argument is "alignTop"
+    // } else if (rect.bottom > window.innerHeight) {
+    //   current.scrollIntoView(false);
+    // }
+  }
+}
+
+function scrollHandler(positionY) {
+  // scrollHandlerForHeader();
+  scrollHandlerForBackToTop(positionY);
+  scrollHandlerForTOC(positionY);
+}
+
+////////////////////////////////////////////////////////////////////////////////
+// Theme Toggle
+////////////////////////////////////////////////////////////////////////////////
+function setTheme(mode) {
+  if (mode !== "light" && mode !== "dark" && mode !== "auto") {
+    console.error(`Got invalid theme mode: ${mode}. Resetting to auto.`);
+    mode = "auto";
+  }
+
+  document.body.dataset.theme = mode;
+  localStorage.setItem("theme", mode);
+  console.log(`Changed to ${mode} mode.`);
+}
+
+function cycleThemeOnce() {
+  const currentTheme = localStorage.getItem("theme") || "auto";
+  const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+
+  if (prefersDark) {
+    // Auto (dark) -> Light -> Dark
+    if (currentTheme === "auto") {
+      setTheme("light");
+    } else if (currentTheme == "light") {
+      setTheme("dark");
+    } else {
+      setTheme("auto");
+    }
+  } else {
+    // Auto (light) -> Dark -> Light
+    if (currentTheme === "auto") {
+      setTheme("dark");
+    } else if (currentTheme == "dark") {
+      setTheme("light");
+    } else {
+      setTheme("auto");
+    }
+  }
+}
+
+////////////////////////////////////////////////////////////////////////////////
+// Setup
+////////////////////////////////////////////////////////////////////////////////
+function setupScrollHandler() {
+  // Taken from https://developer.mozilla.org/en-US/docs/Web/API/Document/scroll_event
+  let last_known_scroll_position = 0;
+  let ticking = false;
+
+  window.addEventListener("scroll", function (e) {
+    last_known_scroll_position = window.scrollY;
+
+    if (!ticking) {
+      window.requestAnimationFrame(function () {
+        scrollHandler(last_known_scroll_position);
+        ticking = false;
+      });
+
+      ticking = true;
+    }
+  });
+  window.scroll();
+}
+
+function setupScrollSpy() {
+  if (tocScroll === null) {
+    return;
+  }
+
+  // Scrollspy -- highlight table on contents, based on scroll
+  // new Gumshoe(".toc-tree a", {
+  //   reflow: true,
+  //   recursive: true,
+  //   navClass: "scroll-current",
+  //   offset: () => {
+  //     let rem = parseFloat(getComputedStyle(document.documentElement).fontSize);
+  //     return header.getBoundingClientRect().height + 0.5 * rem + 1;
+  //   },
+  // });
+}
+
+function setupTheme() {
+  // Attach event handlers for toggling themes
+  const buttons = document.getElementsByClassName("theme-toggle");
+  Array.from(buttons).forEach((btn) => {
+    btn.addEventListener("click", cycleThemeOnce);
+  });
+}
+
+function setup() {
+  setupTheme();
+  setupScrollHandler();
+  setupScrollSpy();
+}
+
+////////////////////////////////////////////////////////////////////////////////
+// Main entrypoint
+////////////////////////////////////////////////////////////////////////////////
+function main() {
+  document.body.parentNode.classList.remove("no-js");
+
+  // header = document.querySelectorAll("header")[1];
+  tocScroll = document.querySelector(".toc-scroll");
+
+  setup();
+}
+
+document.addEventListener("DOMContentLoaded", main);