sphinx-gp-theme 0.0.1a8__py3-none-any.whl

sphinx_gp_theme/__init__.py

@@ -0,0 +1,82 @@
+"""sphinx-gp-theme — Furo child theme for git-pull projects.
+
+Provides a shared visual identity for git-pull project documentation
+by inheriting from Furo and bundling common templates, CSS, and JS.
+
+Examples
+--------
+>>> import pathlib
+
+>>> theme_path = get_theme_path()
+>>> theme_path.is_dir()
+True
+
+>>> (theme_path / "theme.conf").is_file()
+True
+"""
+
+from __future__ import annotations
+
+import pathlib
+import typing as t
+
+if t.TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+__version__ = "0.0.1a8"
+
+
+def get_theme_path() -> pathlib.Path:
+    """Return the path to the sphinx-gp-theme theme directory.
+
+    Returns
+    -------
+    pathlib.Path
+        Absolute path to the theme directory containing
+        ``theme.conf`` and associated templates/static files.
+
+    Examples
+    --------
+    >>> theme_path = get_theme_path()
+    >>> (theme_path / "theme.conf").exists()
+    True
+
+    >>> (theme_path / "static" / "css" / "custom.css").exists()
+    True
+    """
+    return pathlib.Path(__file__).parent / "theme"
+
+
+def setup(app: Sphinx) -> dict[str, bool | str]:
+    """Register the bundled theme with Sphinx.
+
+    Parameters
+    ----------
+    app : Sphinx
+        The Sphinx application object.
+
+    Returns
+    -------
+    dict[str, bool | str]
+        Extension metadata for Sphinx.
+
+    Examples
+    --------
+    >>> class FakeApp:
+    ...     def __init__(self) -> None:
+    ...         self.calls: list[tuple[str, pathlib.Path]] = []
+    ...     def add_html_theme(self, name: str, theme_path: pathlib.Path) -> None:
+    ...         self.calls.append((name, theme_path))
+    >>> fake = FakeApp()
+    >>> metadata = setup(fake)  # type: ignore[arg-type]
+    >>> fake.calls[0][0]
+    'sphinx-gp-theme'
+    >>> metadata["parallel_read_safe"]
+    True
+    """
+    app.add_html_theme("sphinx-gp-theme", get_theme_path())
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+        "version": __version__,
+    }

sphinx_gp_theme/theme/page.html

@@ -0,0 +1,78 @@
+{% extends "furo/page.html" %}
+{%- block extrahead %}
+  {{ super() }}
+  {%- for href in font_preload_hrefs|default([]) %}
+  <link rel="preload" href="{{ pathto('_static/fonts/' + href, 1) }}" as="font" type="font/woff2" crossorigin="">
+  {%- endfor %}
+  {%- if font_faces is defined and font_faces %}
+  <style id="sphinx-fonts">
+  {%- for face in font_faces %}
+  @font-face {
+    font-family: "{{ face.family }}";
+    font-style: {{ face.style }};
+    font-weight: {{ face.weight }};
+    font-display: block;
+    src: url("{{ pathto('_static/fonts/' + face.filename, 1) }}") format("woff2");
+  }
+  {%- endfor %}
+  {%- for fb in font_fallbacks|default([]) %}
+  @font-face {
+    font-family: "{{ fb.family }}";
+    src: {{ fb.src }};
+    size-adjust: {{ fb.size_adjust }};
+    ascent-override: {{ fb.ascent_override }};
+    descent-override: {{ fb.descent_override }};
+    line-gap-override: {{ fb.line_gap_override }};
+  }
+  {%- endfor %}
+  body {
+  {%- for var, value in font_css_variables.items() %}
+    {{ var }}: {{ value }};
+  {%- endfor %}
+  }
+  </style>
+  {%- endif %}
+  {%- if theme_show_meta_manifest_tag == true %}
+  <link rel="manifest" href="/manifest.json">
+  {% endif -%}
+  {%- if theme_show_meta_og_tags == true %}
+  <meta name="description" content="{{ theme_project_description }}">
+
+  <!-- Open Graph / Facebook -->
+  <meta property="og:type" content="website">
+  <meta property="og:url" content="{{ theme_project_url }}/">
+  <meta property="og:title" content="{{ theme_project_title }}">
+  <meta property="og:description" content="{{ theme_project_description }}">
+  <meta property="og:image" itemprop="image" content="{{ theme_project_url }}/_static/img/icons/icon-192x192.png">
+
+  <!-- Twitter -->
+  <meta property="twitter:card" content="summary_large_image">
+  <meta property="twitter:url" content="{{ theme_project_url }} ">
+  <meta property="twitter:title" content="{{ theme_project_title }}">
+  <meta property="twitter:description" content="{{ theme_project_description }}">
+  <meta property="twitter:image" content="{{ theme_project_url }}/_static/img/icons/icon-512x512.png">
+  {% endif -%}
+  {%- if theme_show_meta_app_icon_tags == true %}
+  <meta name="theme-color" content="#ffffff">
+  <meta name="application-name" content="{{ theme_project_name }}">
+
+  <link rel="shortcut icon" href="/_static/favicon.ico">
+  <link rel="icon" type="image/png" sizes="512x512" href="/_static/img/icons/icon-512x512.png">
+  <link rel="icon" type="image/png" sizes="192x192" href="/_static/img/icons/icon-192x192.png">
+  <link rel="icon" type="image/png" sizes="32x32" href="/_static/img/icons/icon-32x32.png">
+  <link rel="icon" type="image/png" sizes="96x96" href="/_static/img/icons/icon-96x96.png">
+  <link rel="icon" type="image/png" sizes="16x16" href="/_static/img/icons/icon-16x16.png">
+
+  <!-- Apple -->
+  <meta name="apple-mobile-web-app-title" content="{{ theme_project_name }}">
+
+  <link rel="apple-touch-icon" sizes="192x192" href="/_static/img/icons/icon-192x192.png">
+
+  <!-- Microsoft -->
+  <meta name="msapplication-TileColor" content="#ffffff">
+  <meta name="msapplication-TileImage" content="/_static/img/icons/ms-icon-144x144.png">
+  {% endif -%}
+  {%- if theme_mask_icon %}
+  <link rel="mask-icon" href="{{ theme_mask_icon }}" color="grey">
+  {%- endif %}
+{% endblock %}

sphinx_gp_theme/theme/sidebar/brand.html

@@ -0,0 +1,18 @@
+<a class="sidebar-brand{% if logo %} centered{% endif %}" href="{{ pathto(master_doc) }}">
+  {%- block brand_content %}
+  {%- if logo_url %}
+  <div class="sidebar-logo-container">
+    <img class="sidebar-logo" src="{{ logo_url }}" width="200" height="200" decoding="async" alt="Logo"/>
+  </div>
+  {%- endif %}
+  {%- if theme_light_logo and theme_dark_logo %}
+  <div class="sidebar-logo-container">
+    <img class="sidebar-logo only-light" src="{{ pathto('_static/' + theme_light_logo, 1) }}" width="200" height="200" decoding="async" alt="Light Logo"/>
+    <img class="sidebar-logo only-dark" src="{{ pathto('_static/' + theme_dark_logo, 1) }}" width="200" height="200" decoding="async" alt="Dark Logo"/>
+  </div>
+  {%- endif %}
+  {% if not theme_sidebar_hide_name %}
+  <span class="sidebar-brand-text">{{ docstitle if docstitle else project }}</span>
+  {%- endif %}
+  {% endblock brand_content %}
+</a>

sphinx_gp_theme/theme/sidebar/projects.html

@@ -0,0 +1,84 @@
+<div class="sidebar-tree projects" id="sidebar-projects">
+  <p class="caption" role="heading">
+    <span class="caption-text"
+      >team git-pull / <a href="https://tony.sh">Tony Narlock</a></span
+    >:
+  </p>
+
+  <p class="indented-block">
+    <span class="project-name">vcs-python</span>
+    <a class="internal" href="https://vcspull.git-pull.com">vcspull</a>
+    (<a class="internal" href="https://libvcs.git-pull.com">libvcs</a>),
+    <a class="internal" href="https://g.git-pull.com">g</a>
+  </p>
+  <p class="indented-block">
+    <span class="project-name">tmux-python</span>
+    <span class="indent">
+      <a class="internal" href="https://tmuxp.git-pull.com">tmuxp</a>
+    </span>
+    <span class="indent">
+      <a class="internal" href="https://libtmux.git-pull.com">libtmux</a>
+      (<a class="internal" href="https://libtmux-mcp.git-pull.com">mcp</a>,
+      <a class="internal" href="https://libtmux.git-pull.com/pytest-plugin/">pytest</a>)
+    </span>
+  </p>
+
+  <p class="indented-block">
+    <span class="project-name">cihai</span>
+    <span class="indent">
+      <a class="internal" href="https://unihan-etl.git-pull.com">unihan-etl</a>
+      (<a class="internal" href="https://unihan-db.git-pull.com">db</a>)
+    </span>
+    <span class="indent">
+      <a class="internal" href="https://cihai.git-pull.com">cihai</a>
+      (<a class="internal" href="https://cihai-cli.git-pull.com">cli</a>)
+    </span>
+  </p>
+
+  <p class="indented-block">
+    <span class="project-name">django</span>
+    <span class="indent">
+      <a class="internal" href="https://django-slugify-processor.git-pull.com">django-slugify-processor</a>
+    </span>
+    <span class="indent">
+      <a class="internal" href="https://django-docutils.git-pull.com">django-docutils</a>
+    </span>
+  </p>
+
+  <p class="indented-block">
+    <span class="project-name">docs + tests</span>
+    <span class="indent">
+      <a class="internal" href="https://gp-libs.git-pull.com">gp-libs</a>
+    </span>
+  </p>
+
+  <p class="indented-block">
+    <span class="project-name">web</span>
+    <span class="indent">
+      <a class="internal" href="https://social-embed.org">social-embed</a>
+    </span>
+  </p>
+</div>
+<script type="text/javascript">
+(() => {
+  const sidebar = document.getElementById("sidebar-projects");
+  const loc = window.location;
+  sidebar.querySelectorAll("a[href]").forEach((link) => {
+    const url = new URL(link.href, loc.origin);
+    const sameHost = url.hostname === loc.hostname;
+    const hasPath = url.pathname.replace(/\/+$/, "").length > 0;
+    // Links with a pathname: match origin + path prefix (e.g. /pytest-plugin/)
+    // Links without: match hostname only (e.g. https://libtmux.git-pull.com)
+    const isActive = hasPath
+      ? sameHost && loc.pathname.startsWith(url.pathname.replace(/\/+$/, ""))
+      : sameHost;
+    if (isActive && !link.classList.contains("active")) {
+      const d = document.createElement('span');
+      d.textContent = link.textContent;
+      d.classList.add("active");
+      link.parentNode.replaceChild(d, link);
+    }
+  });
+  sidebar.classList.add('ready');
+})()
+</script>

sphinx_gp_theme/theme/static/css/argparse-highlight.css

@@ -0,0 +1,437 @@
+/*
+ * Argparse/CLI Highlighting Styles
+ *
+ * Styles for CLI inline roles and argparse help output highlighting.
+ * Uses "One Dark" inspired color palette (Python 3.14 argparse style).
+ *
+ * Color Palette:
+ *   Background:    #282C34
+ *   Default text:  #CCCED4
+ *   Usage label:   #61AFEF (blue, bold)
+ *   Program name:  #C678DD (purple, bold)
+ *   Subcommands:   #98C379 (green)
+ *   Options:       #56B6C2 (teal)
+ *   Metavars:      #E5C07B (yellow, italic)
+ *   Choices:       #98C379 (green)
+ *   Headings:      #E5E5E5 (bright, bold)
+ *   Punctuation:   #CCCED4
+ */
+
+/* ==========================================================================
+   Inline Role Styles
+   ========================================================================== */
+
+/*
+ * Shared monospace font and code font-size for all CLI inline roles
+ */
+.cli-option,
+.cli-metavar,
+.cli-command,
+.cli-default,
+.cli-choice {
+	font-family: var(--font-stack--monospace);
+	font-size: var(--code-font-size);
+}
+
+/*
+ * CLI Options
+ *
+ * Long options (--verbose) and short options (-h) both use teal color.
+ */
+.cli-option-long,
+.cli-option-short {
+	color: #56b6c2;
+}
+
+/*
+ * CLI Metavars
+ *
+ * Placeholder values like FILE, PATH, DIRECTORY.
+ * Yellow/amber to indicate "replace me" - distinct from flags (teal).
+ */
+.cli-metavar {
+	color: #e5c07b;
+	font-style: italic;
+}
+
+/*
+ * CLI Commands and Choices
+ *
+ * Both use green to indicate valid enumerated values.
+ * Commands: subcommand names like sync, add, list
+ * Choices: enumeration values like json, yaml, table
+ */
+.cli-command,
+.cli-choice {
+	color: #98c379;
+}
+
+.cli-command {
+	font-weight: bold;
+}
+
+/*
+ * CLI Default Values
+ *
+ * Default values shown in help text like None, "auto".
+ * Subtle styling to not distract from options.
+ */
+.cli-default {
+	color: #ccced4;
+	font-style: italic;
+}
+
+/* ==========================================================================
+   Argparse Code Block Highlighting
+   ========================================================================== */
+
+/*
+ * These styles apply within Pygments-highlighted code blocks using the
+ * argparse, argparse-usage, or argparse-help lexers.
+ */
+
+/* Usage heading "usage:" - bold blue */
+.highlight-argparse .gh,
+.highlight-argparse-usage .gh,
+.highlight-argparse-help .gh {
+	color: #61afef;
+	font-weight: bold;
+}
+
+/* Section headers like "positional arguments:", "options:" - neutral bright */
+.highlight-argparse .gs,
+.highlight-argparse-help .gs {
+	color: #e5e5e5;
+	font-weight: bold;
+}
+
+/* Long options --foo - teal */
+.highlight-argparse .nt,
+.highlight-argparse-usage .nt,
+.highlight-argparse-help .nt {
+	color: #56b6c2;
+	font-weight: normal;
+}
+
+/* Short options -h - teal (same as long) */
+.highlight-argparse .na,
+.highlight-argparse-usage .na,
+.highlight-argparse-help .na {
+	color: #56b6c2;
+	font-weight: normal;
+}
+
+/* Metavar placeholders FILE, PATH - yellow/amber italic */
+.highlight-argparse .nv,
+.highlight-argparse-usage .nv,
+.highlight-argparse-help .nv {
+	color: #e5c07b;
+	font-style: italic;
+}
+
+/* Command/program names - purple bold */
+.highlight-argparse .nl,
+.highlight-argparse-usage .nl,
+.highlight-argparse-help .nl {
+	color: #c678dd;
+	font-weight: bold;
+}
+
+/* Subcommands - bold green */
+.highlight-argparse .nf,
+.highlight-argparse-usage .nf,
+.highlight-argparse-help .nf {
+	color: #98c379;
+	font-weight: bold;
+}
+
+/* Choice values - green */
+.highlight-argparse .no,
+.highlight-argparse-usage .no,
+.highlight-argparse-help .no,
+.highlight-argparse .nc,
+.highlight-argparse-usage .nc,
+.highlight-argparse-help .nc {
+	color: #98c379;
+}
+
+/* Punctuation [], {}, () - neutral gray */
+.highlight-argparse .p,
+.highlight-argparse-usage .p,
+.highlight-argparse-help .p {
+	color: #ccced4;
+}
+
+/* Operators like | - neutral gray */
+.highlight-argparse .o,
+.highlight-argparse-usage .o,
+.highlight-argparse-help .o {
+	color: #ccced4;
+	font-weight: normal;
+}
+
+/* ==========================================================================
+   Argparse Directive Highlighting (.. argparse:: output)
+   ========================================================================== */
+
+/*
+ * These styles apply to the argparse directive output which uses custom
+ * nodes rendered by sphinx_autodoc_argparse. The directive adds highlight spans
+ * directly to the HTML output.
+ */
+
+/*
+ * Usage Block (.argparse-usage)
+ *
+ * The usage block now has both .argparse-usage and .highlight-argparse-usage
+ * classes. The .highlight-argparse-usage selectors above already handle the
+ * token highlighting. These selectors provide fallback and ensure consistent
+ * styling.
+ */
+
+/* Usage block container - match Pygments monokai background and code block styling */
+pre.argparse-usage {
+	background: var(--argparse-code-background);
+	font-size: var(--code-font-size);
+	padding: 0.625rem 0.875rem;
+	line-height: 1.5;
+	border-radius: 0.2rem;
+	scrollbar-color: var(--color-foreground-border) transparent;
+	scrollbar-width: thin;
+}
+
+.argparse-usage .gh {
+	color: #61afef;
+	font-weight: bold;
+}
+
+.argparse-usage .nt {
+	color: #56b6c2;
+	font-weight: normal;
+}
+
+.argparse-usage .na {
+	color: #56b6c2;
+	font-weight: normal;
+}
+
+.argparse-usage .nv {
+	color: #e5c07b;
+	font-style: italic;
+}
+
+.argparse-usage .nl {
+	color: #c678dd;
+	font-weight: bold;
+}
+
+.argparse-usage .nf {
+	color: #98c379;
+	font-weight: bold;
+}
+
+.argparse-usage .no,
+.argparse-usage .nc {
+	color: #98c379;
+}
+
+.argparse-usage .o {
+	color: #ccced4;
+	font-weight: normal;
+}
+
+.argparse-usage .p {
+	color: #ccced4;
+}
+
+/*
+ * Argument Name (<dt class="argparse-argument-name">)
+ *
+ * The argument names in the dl/dt structure are highlighted with
+ * semantic spans for options and metavars.
+ */
+.argparse-argument-name .nt {
+	color: #56b6c2;
+	font-weight: normal;
+}
+
+.argparse-argument-name .na {
+	color: #56b6c2;
+	font-weight: normal;
+}
+
+.argparse-argument-name .nv {
+	color: #e5c07b;
+	font-style: italic;
+}
+
+.argparse-argument-name .nl {
+	color: #c678dd;
+	font-weight: bold;
+}
+
+/* ==========================================================================
+   Argument Wrapper and Linking Styles
+   ========================================================================== */
+
+/*
+ * Argparse-specific code background (monokai #272822)
+ * Uses a custom variable to avoid affecting Furo's --color-inline-code-background.
+ */
+:root {
+	--argparse-code-background: #272822;
+}
+
+/*
+ * Background styling for argument names - subtle background like code.literal
+ * This provides visual weight and hierarchy for argument definitions.
+ */
+.argparse-argument-name {
+	background: var(--argparse-code-background);
+	border-radius: 0.2rem;
+	padding: 0.485rem 0.875rem;
+	font-family: var(--font-stack--monospace);
+	font-size: var(--code-font-size);
+	width: fit-content;
+	position: relative;
+}
+
+/*
+ * Wrapper for linking - enables scroll-margin for fixed header navigation
+ * and :target pseudo-class for highlighting when linked.
+ */
+.argparse-argument-wrapper {
+	scroll-margin-top: 2.5rem;
+}
+
+/*
+ * Headerlink anchor (¶) - hidden until hover
+ * Positioned outside the dt element to the right.
+ * Follows Sphinx documentation convention for linkable headings.
+ */
+.argparse-argument-name .headerlink {
+	visibility: hidden;
+	position: absolute;
+	right: -1.5rem;
+	top: 50%;
+	transform: translateY(-50%);
+	color: var(--color-foreground-secondary);
+	text-decoration: none;
+}
+
+/*
+ * Show headerlink on hover or when targeted via URL fragment
+ */
+.argparse-argument-wrapper:hover .headerlink,
+.argparse-argument-wrapper:target .headerlink {
+	visibility: visible;
+}
+
+.argparse-argument-name .headerlink:hover:not(:visited) {
+	color: var(--color-foreground-primary);
+}
+
+/*
+ * Light mode headerlink color overrides
+ * Needed because code block has dark background regardless of theme
+ */
+body[data-theme="light"] .argparse-argument-name .headerlink {
+	color: #9ca0a5;
+
+	&:hover:not(:visited) {
+		color: #cfd0d0;
+	}
+}
+
+@media (prefers-color-scheme: light) {
+	body:not([data-theme="dark"]) .argparse-argument-name .headerlink {
+		color: #9ca0a5;
+
+		&:hover:not(:visited) {
+			color: #cfd0d0;
+		}
+	}
+}
+
+/*
+ * Highlight when targeted via URL fragment
+ * Uses Furo's highlight-on-target color for consistency.
+ */
+.argparse-argument-wrapper:target .argparse-argument-name {
+	background-color: var(--color-highlight-on-target);
+}
+
+/*
+ * Argument metadata definition list
+ *
+ * Renders metadata (Default, Type, Choices, Required) as a horizontal
+ * flexbox of key-value pairs and standalone tags.
+ */
+.argparse-argument-meta {
+	margin: 0.5rem 0 0 0;
+	padding: 0;
+	display: flex;
+	flex-wrap: wrap;
+	gap: 0.5rem 1rem;
+	align-items: center;
+}
+
+.argparse-meta-item {
+	display: flex;
+	align-items: center;
+	gap: 0.25rem;
+}
+
+.argparse-meta-key {
+	color: var(--color-foreground-secondary, #6c757d);
+	font-size: var(--code-font-size);
+}
+
+.argparse-meta-key::after {
+	content: ":";
+}
+
+.argparse-meta-value .nv {
+	background: var(--argparse-code-background);
+	border-radius: 0.2rem;
+	padding: 0.1rem 0.3rem;
+	font-family: var(--font-stack--monospace);
+	font-size: var(--code-font-size);
+	color: #e5c07b;
+}
+
+/*
+ * Meta tag (e.g., "Required") - follows Furo's guilabel pattern
+ * Uses semi-transparent amber background with border for visibility
+ * without the harshness of solid fills. Amber conveys "needs attention".
+ */
+.argparse-meta-tag {
+	background-color: #fef3c780;
+	border: 1px solid #fcd34d80;
+	color: var(--color-foreground-primary);
+	font-size: var(--code-font-size);
+	padding: 0.1rem 0.4rem;
+	border-radius: 0.2rem;
+	font-weight: 500;
+}
+
+/* Dark mode: darker amber with adjusted border */
+body[data-theme="dark"] .argparse-meta-tag {
+	background-color: #78350f60;
+	border-color: #b4530980;
+}
+
+@media (prefers-color-scheme: dark) {
+	body:not([data-theme="light"]) .argparse-meta-tag {
+		background-color: #78350f60;
+		border-color: #b4530980;
+	}
+}
+
+/*
+ * Help text description
+ * Adds spacing above for visual separation from argument name.
+ */
+.argparse-argument-help {
+	padding-block-start: 0.5rem;
+}