sphinx-fonts 0.0.1a0__tar.gz

sphinx_fonts-0.0.1a0/.gitignore

@@ -0,0 +1,225 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Generated by sphinx_fonts extension (downloaded at build time)
+docs/_static/fonts/
+docs/_static/css/fonts.css
+
+# Claude Code
+**/CLAUDE.local.md
+**/CLAUDE.*.md
+**/.claude/settings.local.json
+
+# Playwright MCP
+.playwright-mcp/
+
+# Misc
+.vim/
+*.lprof
+pip-wheel-metadata/
+monkeytype.sqlite3

sphinx_fonts-0.0.1a0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: sphinx-fonts
+Version: 0.0.1a0
+Summary: Sphinx extension for self-hosted fonts via Fontsource CDN
+Project-URL: Repository, https://github.com/git-pull/gp-sphinx
+Author-email: Tony Narlock <tony@git-pull.com>
+License: MIT
+Keywords: fonts,fontsource,self-hosted,sphinx
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Sphinx
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Documentation :: Sphinx
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.10
+Requires-Dist: sphinx
+Description-Content-Type: text/markdown
+
+# sphinx-fonts
+
+Sphinx extension for self-hosted fonts via [Fontsource](https://fontsource.org/) CDN.
+
+Downloads font files at build time, caches them locally (`~/.cache/sphinx-fonts`), and
+injects `@font-face` declarations via Jinja2 template context.
+
+## Install
+
+```console
+$ pip install sphinx-fonts
+```
+
+## Usage
+
+In your `docs/conf.py`:
+
+```python
+extensions = ["sphinx_fonts"]
+
+sphinx_fonts = [
+    {
+        "family": "IBM Plex Sans",
+        "package": "@fontsource/ibm-plex-sans",
+        "version": "5.2.8",
+        "weights": [400, 500, 600, 700],
+        "styles": ["normal", "italic"],
+        "subset": "latin",
+    },
+]
+
+sphinx_font_css_variables = {
+    "--font-stack": '"IBM Plex Sans", sans-serif',
+}
+```
+
+Requires a `page.html` template override that reads the `font_faces` and
+`font_preload_hrefs` context variables. See the
+[gp-sphinx docs](https://gp-sphinx.git-pull.com) for a complete template example.

sphinx_fonts-0.0.1a0/README.md

@@ -0,0 +1,39 @@
+# sphinx-fonts
+
+Sphinx extension for self-hosted fonts via [Fontsource](https://fontsource.org/) CDN.
+
+Downloads font files at build time, caches them locally (`~/.cache/sphinx-fonts`), and
+injects `@font-face` declarations via Jinja2 template context.
+
+## Install
+
+```console
+$ pip install sphinx-fonts
+```
+
+## Usage
+
+In your `docs/conf.py`:
+
+```python
+extensions = ["sphinx_fonts"]
+
+sphinx_fonts = [
+    {
+        "family": "IBM Plex Sans",
+        "package": "@fontsource/ibm-plex-sans",
+        "version": "5.2.8",
+        "weights": [400, 500, 600, 700],
+        "styles": ["normal", "italic"],
+        "subset": "latin",
+    },
+]
+
+sphinx_font_css_variables = {
+    "--font-stack": '"IBM Plex Sans", sans-serif',
+}
+```
+
+Requires a `page.html` template override that reads the `font_faces` and
+`font_preload_hrefs` context variables. See the
+[gp-sphinx docs](https://gp-sphinx.git-pull.com) for a complete template example.

sphinx_fonts-0.0.1a0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "sphinx-fonts"
+version = "0.0.1a0"
+description = "Sphinx extension for self-hosted fonts via Fontsource CDN"
+requires-python = ">=3.10,<4.0"
+authors = [
+  {name = "Tony Narlock", email = "tony@git-pull.com"}
+]
+license = { text = "MIT" }
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "License :: OSI Approved :: MIT License",
+  "Framework :: Sphinx",
+  "Framework :: Sphinx :: Extension",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Documentation",
+  "Topic :: Documentation :: Sphinx",
+  "Typing :: Typed",
+]
+readme = "README.md"
+keywords = ["sphinx", "fonts", "fontsource", "self-hosted"]
+dependencies = [
+  "sphinx",
+]
+
+[project.urls]
+Repository = "https://github.com/git-pull/gp-sphinx"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sphinx_fonts"]

sphinx_fonts-0.0.1a0/src/sphinx_fonts/__init__.py

@@ -0,0 +1,270 @@
+"""Sphinx extension for self-hosted fonts via Fontsource CDN.
+
+Downloads font files at build time, caches them locally, and passes
+structured font data to the template context for inline @font-face CSS.
+
+Examples
+--------
+>>> from sphinx_fonts import _cache_dir
+
+>>> _cache_dir().name
+'sphinx-fonts'
+"""
+
+from __future__ import annotations
+
+import logging
+import pathlib
+import shutil
+import typing as t
+import urllib.error
+import urllib.request
+
+if t.TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+__version__ = "0.0.1a0"
+
+CDN_TEMPLATE = (
+    "https://cdn.jsdelivr.net/npm/{package}@{version}"
+    "/files/{font_id}-{subset}-{weight}-{style}.woff2"
+)
+
+
+class SetupDict(t.TypedDict):
+    """Return type for Sphinx extension setup()."""
+
+    version: str
+    parallel_read_safe: bool
+    parallel_write_safe: bool
+
+
+class _FontConfigRequired(t.TypedDict):
+    family: str
+    package: str
+    version: str
+    weights: list[int]
+    styles: list[str]
+
+
+class FontConfig(_FontConfigRequired, total=False):
+    """A single font family configuration entry.
+
+    Required keys: ``family``, ``package``, ``version``, ``weights``, ``styles``.
+    Optional key: ``subset`` (defaults to ``"latin"`` when omitted).
+    """
+
+    subset: str
+
+
+def _cache_dir() -> pathlib.Path:
+    """Return the local font cache directory.
+
+    Returns
+    -------
+    pathlib.Path
+        Path to ``~/.cache/sphinx-fonts``.
+
+    Examples
+    --------
+    >>> _cache_dir().name
+    'sphinx-fonts'
+    """
+    return pathlib.Path.home() / ".cache" / "sphinx-fonts"
+
+
+def _cdn_url(
+    package: str,
+    version: str,
+    font_id: str,
+    subset: str,
+    weight: int,
+    style: str,
+) -> str:
+    """Build a Fontsource CDN URL for a specific font variant.
+
+    Parameters
+    ----------
+    package : str
+        Fontsource npm package name (e.g., ``@fontsource/ibm-plex-sans``).
+    version : str
+        Package version.
+    font_id : str
+        Font identifier (last segment of package name).
+    subset : str
+        Unicode subset (e.g., ``latin``).
+    weight : int
+        Font weight (e.g., 400, 700).
+    style : str
+        Font style (e.g., ``normal``, ``italic``).
+
+    Returns
+    -------
+    str
+        Full CDN URL.
+
+    Examples
+    --------
+    >>> url = _cdn_url(
+    ...     "@fontsource/ibm-plex-sans", "5.2.8",
+    ...     "ibm-plex-sans", "latin", 400, "normal",
+    ... )
+    >>> "ibm-plex-sans-latin-400-normal.woff2" in url
+    True
+    """
+    return CDN_TEMPLATE.format(
+        package=package,
+        version=version,
+        font_id=font_id,
+        subset=subset,
+        weight=weight,
+        style=style,
+    )
+
+
+def _download_font(url: str, dest: pathlib.Path) -> bool:
+    """Download a font file from the CDN, using local cache.
+
+    Parameters
+    ----------
+    url : str
+        URL to download from.
+    dest : pathlib.Path
+        Local path to write the file to.
+
+    Returns
+    -------
+    bool
+        True if the file is available (downloaded or cached).
+    """
+    if dest.exists():
+        logger.debug("font cached: %s", dest.name)
+        return True
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        urllib.request.urlretrieve(url, dest)
+        logger.info("downloaded font: %s", dest.name)
+    except (urllib.error.URLError, OSError):
+        if dest.exists():
+            dest.unlink()
+        logger.warning("failed to download font: %s", url)
+        return False
+    return True
+
+
+def _on_builder_inited(app: Sphinx) -> None:
+    """Download fonts and prepare template context data on builder init."""
+    if app.builder.format != "html":
+        return
+
+    fonts: list[FontConfig] = app.config.sphinx_fonts
+    variables: dict[str, str] = app.config.sphinx_font_css_variables
+    if not fonts:
+        return
+
+    cache = _cache_dir()
+    static_dir = pathlib.Path(app.outdir) / "_static"
+    fonts_dir = static_dir / "fonts"
+    fonts_dir.mkdir(parents=True, exist_ok=True)
+
+    font_faces: list[dict[str, str]] = []
+    for font in fonts:
+        font_id = font["package"].split("/")[-1]
+        version = font["version"]
+        package = font["package"]
+        subset = font.get("subset", "latin")
+        for weight in font["weights"]:
+            for style in font["styles"]:
+                filename = f"{font_id}-{subset}-{weight}-{style}.woff2"
+                cached = cache / filename
+                url = _cdn_url(package, version, font_id, subset, weight, style)
+                if _download_font(url, cached):
+                    shutil.copy2(cached, fonts_dir / filename)
+                    font_faces.append(
+                        {
+                            "family": font["family"],
+                            "style": style,
+                            "weight": str(weight),
+                            "filename": filename,
+                        }
+                    )
+
+    preload_hrefs: list[str] = []
+    preload_specs: list[tuple[str, int, str]] = app.config.sphinx_font_preload
+    for family_name, weight, style in preload_specs:
+        for font in fonts:
+            if font["family"] == family_name:
+                font_id = font["package"].split("/")[-1]
+                subset = font.get("subset", "latin")
+                filename = f"{font_id}-{subset}-{weight}-{style}.woff2"
+                preload_hrefs.append(filename)
+                break
+
+    fallbacks: list[dict[str, str]] = app.config.sphinx_font_fallbacks
+
+    app._font_preload_hrefs = preload_hrefs  # type: ignore[attr-defined]
+    app._font_faces = font_faces  # type: ignore[attr-defined]
+    app._font_fallbacks = fallbacks  # type: ignore[attr-defined]
+    app._font_css_variables = variables  # type: ignore[attr-defined]
+
+
+def _on_html_page_context(
+    app: Sphinx,
+    pagename: str,
+    templatename: str,
+    context: dict[str, t.Any],
+    doctree: t.Any,
+) -> None:
+    """Inject font data into Jinja2 template context."""
+    context["font_preload_hrefs"] = getattr(app, "_font_preload_hrefs", [])
+    context["font_faces"] = getattr(app, "_font_faces", [])
+    context["font_fallbacks"] = getattr(app, "_font_fallbacks", [])
+    context["font_css_variables"] = getattr(app, "_font_css_variables", {})
+
+
+def setup(app: Sphinx) -> SetupDict:
+    """Register config values, events, and return extension metadata.
+
+    Parameters
+    ----------
+    app : Sphinx
+        The Sphinx application object.
+
+    Returns
+    -------
+    SetupDict
+        Extension metadata.
+    """
+    app.add_config_value(
+        "sphinx_fonts",
+        [],
+        "html",
+        description="Font family dicts (family, package, version, weights, styles).",
+    )
+    app.add_config_value(
+        "sphinx_font_fallbacks",
+        [],
+        "html",
+        description="Fallback @font-face declarations with metric overrides for CLS.",
+    )
+    app.add_config_value(
+        "sphinx_font_css_variables",
+        {},
+        "html",
+        description="CSS custom properties for Furo font stacks (e.g. --font-stack)",
+    )
+    app.add_config_value(
+        "sphinx_font_preload",
+        [],
+        "html",
+        description="Critical font variants to preload (family, weight, style).",
+    )
+    app.connect("builder-inited", _on_builder_inited)
+    app.connect("html-page-context", _on_html_page_context)
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }