sphinx-gp-opengraph 0.0.1a10__tar.gz

sphinx_gp_opengraph-0.0.1a10/.gitignore

@@ -0,0 +1,228 @@
+# 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/
+
+# Repo-local pytest mirror (do not track — validator-only)
+out/
+
+# Misc
+.vim/
+*.lprof
+pip-wheel-metadata/
+monkeytype.sqlite3

sphinx_gp_opengraph-0.0.1a10/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: sphinx-gp-opengraph
+Version: 0.0.1a10
+Summary: OpenGraph and Twitter meta-tag emission for Sphinx — matplotlib-free
+Project-URL: Repository, https://github.com/git-pull/gp-sphinx
+Author-email: Tony Narlock <tony@git-pull.com>
+License: MIT
+Keywords: documentation,meta,opengraph,social,sphinx
+Classifier: Development Status :: 3 - Alpha
+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>=8.1
+Description-Content-Type: text/markdown
+
+# sphinx-gp-opengraph
+
+OpenGraph meta-tag emission for Sphinx — a drop-in replacement for
+[`sphinxext-opengraph`](https://github.com/sphinx-doc/sphinxext-opengraph)
+that ships every `ogp_*` config key the upstream supports, minus the
+matplotlib-based social-card generator. No image-rendering dependencies,
+no system-fontconfig surprises.
+
+Part of the [gp-sphinx](https://github.com/git-pull/gp-sphinx)
+documentation platform.
+
+## Install
+
+```console
+$ pip install sphinx-gp-opengraph
+```
+
+When you depend on gp-sphinx, this extension is already loaded — see
+[Auto-derived values](#auto-derived-values-when-used-with-gp-sphinx)
+below. The full config-key reference is auto-generated on the
+[package docs page](https://gp-sphinx.git-pull.com/packages/sphinx-gp-opengraph/)
+from the live `app.add_config_value()` registrations.
+
+## Minimum viable conf.py
+
+```python
+extensions = [
+    "sphinx_gp_opengraph",
+]
+```
+
+```python
+ogp_site_url = "https://example.com/"
+```
+
+```python
+ogp_image = "_static/og-default.png"
+```
+
+A 1200×630 PNG works on Slack, Facebook, LinkedIn, and X/Twitter
+unfurlers. With these three values set, every page rendered by an
+HTML-family builder gains `og:title`, `og:type`, `og:url`,
+`og:site_name`, `og:description`, `og:image`, and `og:image:alt`. A
+matching `<meta name="description">` is emitted when the page does not
+already define one.
+
+## Auto-derived values when used with gp-sphinx
+
+Projects that build through {py:func}`gp_sphinx.config.merge_sphinx_config`
+do not need to set `ogp_site_url`, `ogp_site_name`, or `ogp_image`
+manually. Pass `docs_url=` to `merge_sphinx_config()` and gp-sphinx
+fills all three from that one value. See [the sphinx-gp-opengraph package
+page](../../docs/packages/sphinx-gp-opengraph.md) for the integration story
+and [`configuration.md`](../../docs/configuration.md#from-docs_url)
+for the canonical mapping table.
+
+## Per-page overrides
+
+Set front-matter fields to override the site-wide defaults on a single
+page. MyST syntax shown; reST field-list syntax behaves the same way.
+
+```markdown
+---
+ogp_description_length: 160
+og:image: _static/og/this-page.png
+og:image:alt: A tailored hero for this page
+---
+
+# Page title
+
+Body paragraph that becomes og:description.
+```
+
+| Field | Effect |
+| --- | --- |
+| `og:image` | Replace the site-default image for this page |
+| `og:image:alt` | Replace the alt text for this page |
+| `ogp_description_length` | Override the description-length cap for this page |
+| `ogp_disable: true` | Skip OpenGraph emission entirely on this page |
+
+Any other `og:*` field-list entry is forwarded to the page head verbatim,
+so `og:type`, `og:audio`, etc. work without code changes.
+
+## Twitter cards
+
+sphinx-gp-opengraph does not register a separate `twitter_*` namespace;
+crawlers fall back to `og:*` for most fields. Append explicit Twitter
+markup through `ogp_custom_meta_tags` when you need it:
+
+```python
+ogp_custom_meta_tags = [
+    '<meta name="twitter:card" content="summary_large_image" />',
+    '<meta property="og:image:width" content="1200" />',
+    '<meta property="og:image:height" content="630" />',
+]
+```
+
+## Migration from `sphinxext-opengraph`
+
+Configuration is drop-in compatible — every `ogp_*` key is registered
+with the same name, type, and default — with one behavioural change:
+
+- **`ogp_social_cards` is accepted but ignored.** sphinx-gp-opengraph does not
+  bundle the matplotlib-based card generator the upstream ships. Setting
+  the value emits one `WARNING` at `config-inited`:
+
+  ```text
+  sphinx-gp-opengraph: ogp_social_cards ignored — sphinx-gp-opengraph ships no card generator
+  ```
+
+  Grep your build log for `ogp_social_cards ignored` to find this
+  warning. The replacement workflow lives in the next section.
+
+The recommended replacement is one static PNG per page. Drop them under
+`_static/og/` and point the per-page `og:image` field-list entry at
+each one. The downstream UX is the same as upstream's auto-generated
+cards — just explicit, and with no build-time dependency on matplotlib
+or PIL.
+
+```text
+docs/
+├── _static/
+│   └── og/
+│       ├── default.png
+│       ├── quickstart.png
+│       └── reference.png
+├── quickstart.md
+└── reference.md
+```
+
+```markdown
+---
+og:image: _static/og/quickstart.png
+---
+
+# Quickstart
+```
+
+## See also
+
+- [sphinx-gp-sitemap](https://github.com/git-pull/gp-sphinx/tree/main/packages/sphinx-gp-sitemap)
+  — companion package for `sitemap.xml` emission
+- [gp-sphinx](https://github.com/git-pull/gp-sphinx) — the umbrella
+  docs platform; auto-derives `ogp_site_url`, `ogp_site_name`, and
+  `ogp_image` from a single `docs_url` argument
+- [sphinx-gp-opengraph package page](https://gp-sphinx.git-pull.com/packages/sphinx-gp-opengraph/)
+  — integration story, event hooks, and how-it-works

sphinx_gp_opengraph-0.0.1a10/README.md

@@ -0,0 +1,147 @@
+# sphinx-gp-opengraph
+
+OpenGraph meta-tag emission for Sphinx — a drop-in replacement for
+[`sphinxext-opengraph`](https://github.com/sphinx-doc/sphinxext-opengraph)
+that ships every `ogp_*` config key the upstream supports, minus the
+matplotlib-based social-card generator. No image-rendering dependencies,
+no system-fontconfig surprises.
+
+Part of the [gp-sphinx](https://github.com/git-pull/gp-sphinx)
+documentation platform.
+
+## Install
+
+```console
+$ pip install sphinx-gp-opengraph
+```
+
+When you depend on gp-sphinx, this extension is already loaded — see
+[Auto-derived values](#auto-derived-values-when-used-with-gp-sphinx)
+below. The full config-key reference is auto-generated on the
+[package docs page](https://gp-sphinx.git-pull.com/packages/sphinx-gp-opengraph/)
+from the live `app.add_config_value()` registrations.
+
+## Minimum viable conf.py
+
+```python
+extensions = [
+    "sphinx_gp_opengraph",
+]
+```
+
+```python
+ogp_site_url = "https://example.com/"
+```
+
+```python
+ogp_image = "_static/og-default.png"
+```
+
+A 1200×630 PNG works on Slack, Facebook, LinkedIn, and X/Twitter
+unfurlers. With these three values set, every page rendered by an
+HTML-family builder gains `og:title`, `og:type`, `og:url`,
+`og:site_name`, `og:description`, `og:image`, and `og:image:alt`. A
+matching `<meta name="description">` is emitted when the page does not
+already define one.
+
+## Auto-derived values when used with gp-sphinx
+
+Projects that build through {py:func}`gp_sphinx.config.merge_sphinx_config`
+do not need to set `ogp_site_url`, `ogp_site_name`, or `ogp_image`
+manually. Pass `docs_url=` to `merge_sphinx_config()` and gp-sphinx
+fills all three from that one value. See [the sphinx-gp-opengraph package
+page](../../docs/packages/sphinx-gp-opengraph.md) for the integration story
+and [`configuration.md`](../../docs/configuration.md#from-docs_url)
+for the canonical mapping table.
+
+## Per-page overrides
+
+Set front-matter fields to override the site-wide defaults on a single
+page. MyST syntax shown; reST field-list syntax behaves the same way.
+
+```markdown
+---
+ogp_description_length: 160
+og:image: _static/og/this-page.png
+og:image:alt: A tailored hero for this page
+---
+
+# Page title
+
+Body paragraph that becomes og:description.
+```
+
+| Field | Effect |
+| --- | --- |
+| `og:image` | Replace the site-default image for this page |
+| `og:image:alt` | Replace the alt text for this page |
+| `ogp_description_length` | Override the description-length cap for this page |
+| `ogp_disable: true` | Skip OpenGraph emission entirely on this page |
+
+Any other `og:*` field-list entry is forwarded to the page head verbatim,
+so `og:type`, `og:audio`, etc. work without code changes.
+
+## Twitter cards
+
+sphinx-gp-opengraph does not register a separate `twitter_*` namespace;
+crawlers fall back to `og:*` for most fields. Append explicit Twitter
+markup through `ogp_custom_meta_tags` when you need it:
+
+```python
+ogp_custom_meta_tags = [
+    '<meta name="twitter:card" content="summary_large_image" />',
+    '<meta property="og:image:width" content="1200" />',
+    '<meta property="og:image:height" content="630" />',
+]
+```
+
+## Migration from `sphinxext-opengraph`
+
+Configuration is drop-in compatible — every `ogp_*` key is registered
+with the same name, type, and default — with one behavioural change:
+
+- **`ogp_social_cards` is accepted but ignored.** sphinx-gp-opengraph does not
+  bundle the matplotlib-based card generator the upstream ships. Setting
+  the value emits one `WARNING` at `config-inited`:
+
+  ```text
+  sphinx-gp-opengraph: ogp_social_cards ignored — sphinx-gp-opengraph ships no card generator
+  ```
+
+  Grep your build log for `ogp_social_cards ignored` to find this
+  warning. The replacement workflow lives in the next section.
+
+The recommended replacement is one static PNG per page. Drop them under
+`_static/og/` and point the per-page `og:image` field-list entry at
+each one. The downstream UX is the same as upstream's auto-generated
+cards — just explicit, and with no build-time dependency on matplotlib
+or PIL.
+
+```text
+docs/
+├── _static/
+│   └── og/
+│       ├── default.png
+│       ├── quickstart.png
+│       └── reference.png
+├── quickstart.md
+└── reference.md
+```
+
+```markdown
+---
+og:image: _static/og/quickstart.png
+---
+
+# Quickstart
+```
+
+## See also
+
+- [sphinx-gp-sitemap](https://github.com/git-pull/gp-sphinx/tree/main/packages/sphinx-gp-sitemap)
+  — companion package for `sitemap.xml` emission
+- [gp-sphinx](https://github.com/git-pull/gp-sphinx) — the umbrella
+  docs platform; auto-derives `ogp_site_url`, `ogp_site_name`, and
+  `ogp_image` from a single `docs_url` argument
+- [sphinx-gp-opengraph package page](https://gp-sphinx.git-pull.com/packages/sphinx-gp-opengraph/)
+  — integration story, event hooks, and how-it-works

sphinx_gp_opengraph-0.0.1a10/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "sphinx-gp-opengraph"
+version = "0.0.1a10"
+description = "OpenGraph and Twitter meta-tag emission for Sphinx — matplotlib-free"
+requires-python = ">=3.10,<4.0"
+authors = [
+  {name = "Tony Narlock", email = "tony@git-pull.com"}
+]
+license = { text = "MIT" }
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "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", "opengraph", "meta", "social", "documentation"]
+dependencies = [
+  "sphinx>=8.1",
+]
+
+[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_gp_opengraph"]

sphinx_gp_opengraph-0.0.1a10/src/sphinx_gp_opengraph/__init__.py

@@ -0,0 +1,423 @@
+"""OpenGraph and Twitter meta-tag emission for Sphinx.
+
+Drop-in replacement for ``sphinxext-opengraph`` with the same ``ogp_*``
+configuration surface, minus the matplotlib-based social-card generator.
+The ``ogp_social_cards`` config value is still accepted (so existing
+``conf.py`` files do not error), but setting it emits a one-line warning
+directing users to the static-image alternative.
+
+The ``setup()`` registers every ``ogp_*`` config value and connects the
+``html-page-context`` hook that emits OpenGraph and Twitter ``<meta>``
+tags alongside an optional ``<meta name="description">``.
+
+Examples
+--------
+>>> from sphinx_gp_opengraph import setup
+>>> callable(setup)
+True
+"""
+
+from __future__ import annotations
+
+import html
+import logging
+import os
+import pathlib
+import types
+import typing as t
+import urllib.parse
+
+from docutils import nodes
+from sphinx.application import Sphinx
+
+from sphinx_gp_opengraph._description import get_description
+from sphinx_gp_opengraph._meta import get_meta_description
+from sphinx_gp_opengraph._title import get_title
+
+if t.TYPE_CHECKING:
+    from sphinx.builders import Builder
+    from sphinx.config import Config
+    from sphinx.util.typing import ExtensionMetadata
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+_EXTENSION_VERSION = "0.0.1a10"
+
+DEFAULT_DESCRIPTION_LENGTH = 200
+
+# A selection from
+# https://www.iana.org/assignments/media-types/media-types.xhtml#image
+IMAGE_MIME_TYPES: frozenset[str] = frozenset(
+    {"gif", "apng", "webp", "jpeg", "jpg", "png", "bmp", "heic", "heif", "tiff"},
+)
+
+__all__ = [
+    "DEFAULT_DESCRIPTION_LENGTH",
+    "IMAGE_MIME_TYPES",
+    "setup",
+]
+
+
+def html_page_context(
+    app: Sphinx,
+    pagename: str,
+    templatename: str,
+    context: dict[str, t.Any],
+    doctree: nodes.document,
+) -> None:
+    """Inject OpenGraph / Twitter meta tags into ``context['metatags']``.
+
+    Skipped for the ``epub`` builder and for pages without a resolved
+    doctree (e.g. rendered search indexes).
+    """
+    del pagename, templatename  # sourced from ``context`` when needed
+    if app.builder.name == "epub":
+        return
+    if not doctree:
+        return
+    context["metatags"] += get_tags(
+        context,
+        doctree,
+        config=app.config,
+        builder=app.builder,
+    )
+
+
+def get_tags(
+    context: dict[str, t.Any],
+    doctree: nodes.document,
+    *,
+    config: Config,
+    builder: Builder,
+) -> str:
+    """Compose the block of ``<meta>`` tags for one page.
+
+    Parameters
+    ----------
+    context : dict[str, Any]
+        Sphinx HTML page context (provides ``title``, ``pagename``,
+        ``meta`` field-list, and existing ``metatags`` string).
+    doctree : docutils.nodes.document
+        Resolved doctree for the page, walked to extract the description.
+    config : sphinx.config.Config
+        Project configuration (sources all ``ogp_*`` values).
+    builder : sphinx.builders.Builder
+        Active HTML-family builder (used for per-page URL resolution).
+
+    Returns
+    -------
+    str
+        Newline-terminated block of ``<meta>`` tags ready to append to
+        ``context['metatags']``. Empty when the page sets
+        ``ogp_disable`` in its field list.
+    """
+    fields: dict[str, t.Any] = context.get("meta") or {}
+    if "ogp_disable" in fields:
+        return ""
+
+    tags: dict[str, str] = {}
+    meta_tags: dict[str, str] = {}  # Non-og <meta name="..."> tags
+
+    try:
+        desc_len = int(
+            fields.get("ogp_description_length", config.ogp_description_length),
+        )
+    except ValueError:
+        desc_len = DEFAULT_DESCRIPTION_LENGTH
+
+    title, title_excluding_html = get_title(context["title"])
+    description = get_description(doctree, desc_len, {title, title_excluding_html})
+
+    tags["og:title"] = title
+    tags["og:type"] = config.ogp_type
+
+    if not config.ogp_site_url and os.getenv("READTHEDOCS"):
+        ogp_site_url = _ambient_site_url()
+    else:
+        ogp_site_url = config.ogp_site_url
+
+    ogp_canonical_url = config.ogp_canonical_url or ogp_site_url
+
+    page_url = urllib.parse.urljoin(
+        ogp_canonical_url,
+        builder.get_target_uri(context["pagename"]),
+    )
+    tags["og:url"] = page_url
+
+    site_name = _resolve_site_name(config)
+    if site_name:
+        tags["og:site_name"] = site_name
+
+    if description:
+        tags["og:description"] = description
+        if config.ogp_enable_meta_description and not get_meta_description(
+            context["metatags"],
+        ):
+            meta_tags["description"] = description
+
+    image_url, ogp_image_alt, ogp_use_first_image = _resolve_image(fields, config)
+
+    first_image = None
+    if ogp_use_first_image:
+        found = doctree.next_node(nodes.image)
+        if (
+            found
+            and pathlib.Path(found.get("uri", "")).suffix[1:].lower()
+            in IMAGE_MIME_TYPES
+        ):
+            first_image = found
+            image_url = found["uri"]
+            ogp_image_alt = found.get("alt")
+
+    if image_url:
+        if "og:image" not in fields:
+            image_url_parsed = urllib.parse.urlparse(image_url)
+            if not image_url_parsed.scheme:
+                root = page_url if first_image else ogp_site_url
+                image_url = urllib.parse.urljoin(root, image_url_parsed.path)
+            tags["og:image"] = image_url
+
+        if isinstance(ogp_image_alt, str):
+            tags["og:image:alt"] = ogp_image_alt
+        elif ogp_image_alt is None and site_name:
+            tags["og:image:alt"] = site_name
+        elif ogp_image_alt is None and title:
+            tags["og:image:alt"] = title
+
+    fields.pop("og:image:alt", None)
+
+    # Arbitrary og:* overrides supplied through MyST / field-list frontmatter
+    tags.update({k: v for k, v in fields.items() if k.startswith("og:")})
+
+    return (
+        "\n".join(
+            [_make_tag(p, c) for p, c in tags.items()]
+            + [_make_tag(p, c, "name") for p, c in meta_tags.items()]
+            + list(config.ogp_custom_meta_tags),
+        )
+        + "\n"
+    )
+
+
+def _ambient_site_url() -> str:
+    """Derive a site URL from ReadTheDocs env when ``ogp_site_url`` is unset."""
+    rtd_canonical_url = os.getenv("READTHEDOCS_CANONICAL_URL")
+    if not rtd_canonical_url:
+        msg = "ReadTheDocs did not provide a valid canonical URL"
+        raise RuntimeError(msg)
+    parsed = urllib.parse.urlsplit(rtd_canonical_url)
+    return urllib.parse.urlunsplit(
+        (parsed.scheme, parsed.netloc, parsed.path, "", ""),
+    )
+
+
+def _resolve_site_name(config: Config) -> str | None:
+    """Return the resolved site name or ``None`` when explicitly disabled."""
+    if config.ogp_site_name is False:
+        return None
+    if config.ogp_site_name is None:
+        return t.cast("str", config.project)
+    return t.cast("str", config.ogp_site_name)
+
+
+def _resolve_image(
+    fields: dict[str, t.Any],
+    config: Config,
+) -> tuple[str | None, str | bool | None, bool]:
+    """Return (image_url, alt_text, use_first_image) for this page.
+
+    Per-page field-list ``og:image`` wins; otherwise fall back to
+    ``config.ogp_image`` / ``config.ogp_use_first_image``.
+    """
+    if "og:image" in fields:
+        image_url: str | None = fields["og:image"]
+        ogp_use_first_image = False
+        ogp_image_alt: str | bool | None = fields.get("og:image:alt")
+        fields.pop("og:image", None)
+    else:
+        image_url = config.ogp_image
+        ogp_use_first_image = bool(config.ogp_use_first_image)
+        ogp_image_alt = fields.get("og:image:alt", config.ogp_image_alt)
+    return image_url, ogp_image_alt, ogp_use_first_image
+
+
+def _make_tag(
+    property_: str,
+    content: str,
+    attr: t.Literal["property", "name"] = "property",
+) -> str:
+    """Render one ``<meta>`` tag, HTML-escaping ``&``, ``<``, ``>``, and quotes.
+
+    Centralising the escape here is the boundary that keeps every meta tag
+    safe — titles, site names, descriptions, image alts, and custom
+    field-list values all flow through this function. Per-source escaping
+    (e.g. pre-escaping the description) would either leave other paths
+    unsafe or double-escape (``&`` → ``&amp;`` → ``&amp;amp;``).
+    """
+    safe_content = html.escape(content, quote=True)
+    return f'<meta {attr}="{property_}" content="{safe_content}" />'
+
+
+def _warn_if_social_cards_used(app: Sphinx, config: Config) -> None:
+    """Emit a one-line deprecation warning when ``ogp_social_cards`` is set.
+
+    sphinx-gp-opengraph deliberately omits the matplotlib-based card generator
+    upstream ships. The ``ogp_social_cards`` config value remains
+    registered so existing ``conf.py`` files do not error — but its value
+    is ignored. Users who want per-page social preview images should
+    provide static PNGs and point ``ogp_image`` (plus per-page
+    ``og:image`` frontmatter) at them.
+    """
+    del app  # unused; required by Sphinx's config-inited signature
+    if config.ogp_social_cards:
+        logger.warning(
+            "sphinx-gp-opengraph: ogp_social_cards ignored — "
+            "sphinx-gp-opengraph ships no card generator",
+        )
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    """Register config values and connect the html-page-context hook.
+
+    Parameters
+    ----------
+    app : Sphinx
+        Sphinx application instance.
+
+    Returns
+    -------
+    ExtensionMetadata
+        Extension metadata — version and parallel-build flags.
+
+    Examples
+    --------
+    >>> from sphinx_gp_opengraph import setup
+    >>> callable(setup)
+    True
+    """
+    # ogp_site_url="" allows relative URLs by default. Not officially
+    # supported by OGP but matches upstream sphinxext-opengraph.
+    app.add_config_value(
+        "ogp_site_url",
+        "",
+        "html",
+        types=frozenset({str}),
+        description=(
+            "Site base URL joined with each page's relative path to form "
+            "``og:url``. Required for absolute URLs; auto-derived from "
+            "``docs_url`` under gp-sphinx."
+        ),
+    )
+    app.add_config_value(
+        "ogp_canonical_url",
+        "",
+        "html",
+        types=frozenset({str}),
+        description=(
+            "Separate canonical URL used to build ``og:url``; falls back "
+            "to ``ogp_site_url`` when empty."
+        ),
+    )
+    app.add_config_value(
+        "ogp_description_length",
+        DEFAULT_DESCRIPTION_LENGTH,
+        "html",
+        types=frozenset({int}),
+        description=(
+            "Truncation cap (characters) applied to ``og:description`` "
+            "after extracting the first body paragraph."
+        ),
+    )
+    app.add_config_value(
+        "ogp_image",
+        None,
+        "html",
+        types=frozenset({str, types.NoneType}),
+        description=(
+            "Site-default OpenGraph image path or absolute URL. "
+            "Auto-derived from ``docs_url`` under gp-sphinx; per-page "
+            "``og:image`` front-matter overrides."
+        ),
+    )
+    app.add_config_value(
+        "ogp_image_alt",
+        None,
+        "html",
+        types=frozenset({str, bool, types.NoneType}),
+        description=(
+            "Alt text for ``ogp_image``. Falls back to ``og:site_name`` "
+            "then ``og:title``; ``False`` suppresses the alt tag entirely."
+        ),
+    )
+    app.add_config_value(
+        "ogp_use_first_image",
+        False,
+        "html",
+        types=frozenset({bool}),
+        description=(
+            "When ``True`` and no per-page override is set, use the "
+            "first in-page image as ``og:image``."
+        ),
+    )
+    app.add_config_value(
+        "ogp_type",
+        "website",
+        "html",
+        types=frozenset({str}),
+        description="Value emitted as the ``og:type`` tag.",
+    )
+    app.add_config_value(
+        "ogp_site_name",
+        None,
+        "html",
+        types=frozenset({str, bool, types.NoneType}),
+        description=(
+            "Value emitted as ``og:site_name``. Defaults to the Sphinx "
+            "``project`` name; ``False`` suppresses the tag."
+        ),
+    )
+    # Accepted-but-ignored: warned about in _warn_if_social_cards_used.
+    app.add_config_value(
+        "ogp_social_cards",
+        None,
+        "html",
+        types=frozenset({dict, types.NoneType}),
+        description=(
+            "Accepted-but-ignored compatibility shim for upstream "
+            "``sphinxext-opengraph``. Setting any value emits a one-line "
+            "WARNING at ``config-inited``; provide a static PNG via "
+            "``ogp_image`` or per-page ``og:image`` instead."
+        ),
+    )
+    app.add_config_value(
+        "ogp_custom_meta_tags",
+        (),
+        "html",
+        types=frozenset({list, tuple}),
+        description=(
+            "Raw ``<meta>`` tag strings appended verbatim after the "
+            "structured ``og:*`` block — the supported escape hatch for "
+            "Twitter card declarations and image-dimension hints."
+        ),
+    )
+    app.add_config_value(
+        "ogp_enable_meta_description",
+        True,
+        "html",
+        types=frozenset({bool}),
+        description=(
+            'When ``True``, emit a ``<meta name="description">`` '
+            "mirroring ``og:description`` unless the page already "
+            "defines one."
+        ),
+    )
+
+    app.connect("html-page-context", html_page_context)
+    app.connect("config-inited", _warn_if_social_cards_used)
+
+    return {
+        "version": _EXTENSION_VERSION,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

sphinx_gp_opengraph-0.0.1a10/src/sphinx_gp_opengraph/_description.py

@@ -0,0 +1,169 @@
+"""Extract a plain-text description from a Sphinx doctree.
+
+``get_description`` walks a resolved doctree and returns the first chunk of
+prose that Sphinx would render as the page's visible body, suitable for
+inclusion in an ``og:description`` meta tag. Admonitions, code blocks, and
+invisible nodes are skipped; nested lists are flattened into comma-joined
+text; the result is truncated to ``description_length`` characters with a
+trailing ellipsis.
+
+Ported verbatim from ``sphinxext.opengraph._description_parser`` (v0.13.0).
+
+Examples
+--------
+>>> from sphinx_gp_opengraph._description import get_description, DescriptionParser
+>>> callable(get_description)
+True
+>>> issubclass(DescriptionParser, object)
+True
+"""
+
+from __future__ import annotations
+
+import string
+import typing as t
+
+from docutils import nodes
+
+if t.TYPE_CHECKING:
+    from collections.abc import Set
+
+
+def get_description(
+    doctree: nodes.document,
+    description_length: int,
+    known_titles: Set[str] = frozenset(),
+) -> str:
+    """Return a plain-text description extracted from ``doctree``.
+
+    Parameters
+    ----------
+    doctree : docutils.nodes.document
+        Resolved Sphinx doctree for one page.
+    description_length : int
+        Maximum number of characters to return.
+    known_titles : collections.abc.Set[str]
+        Titles to treat as the page title (skipped from the description).
+
+    Returns
+    -------
+    str
+        Flattened, HTML-escaped description, truncated to
+        ``description_length`` with a trailing ``...`` when truncated.
+    """
+    mcv = DescriptionParser(
+        doctree,
+        desc_len=description_length,
+        known_titles=known_titles,
+    )
+    doctree.walkabout(mcv)
+    return mcv.description
+
+
+class DescriptionParser(nodes.NodeVisitor):
+    """Walk a doctree and accumulate a text description.
+
+    Skips admonitions, invisible nodes, raw blocks, and literal blocks.
+    Titles are separated by colons; list elements by commas; sequential
+    lists by periods.
+
+    Parameters
+    ----------
+    document : docutils.nodes.document
+        The document being walked.
+    desc_len : int
+        Maximum character count for the resulting description.
+    known_titles : collections.abc.Set[str]
+        Titles treated as the page title; the first such title encountered
+        is skipped.
+    """
+
+    def __init__(
+        self,
+        document: nodes.document,
+        *,
+        desc_len: int,
+        known_titles: Set[str] = frozenset(),
+    ) -> None:
+        super().__init__(document)
+        self.description = ""
+        self.desc_len = desc_len
+        self.list_level = 0
+        self.known_titles = known_titles
+        self.first_title_found = False
+
+        # Exceptions can't be raised from dispatch_departure()
+        # This is used to loop the stop call back to the next dispatch_visit()
+        self.stop = False
+
+    def dispatch_visit(self, node: nodes.Node) -> None:
+        """Accumulate text from ``node`` unless it should be skipped."""
+        if self.stop:
+            raise nodes.StopTraversal
+
+        # Skip comments & all admonitions
+        if isinstance(node, (nodes.Admonition, nodes.Invisible)):
+            raise nodes.SkipNode
+
+        # Mark start of nested lists
+        if isinstance(node, nodes.Sequential):
+            self.list_level += 1
+            if self.list_level > 1:
+                self.description += "-"
+
+        # Skip the first title if it's the title of the page
+        if not self.first_title_found and isinstance(node, nodes.title):
+            self.first_title_found = True
+            if node.astext() in self.known_titles:
+                raise nodes.SkipNode
+
+        if isinstance(node, nodes.raw) or isinstance(node.parent, nodes.literal_block):
+            raise nodes.SkipNode
+
+        # Only include leaf nodes in the description
+        if len(node.children) == 0:
+            text = node.astext().replace("\r", "").replace("\n", " ").strip()
+
+            # HTML escaping happens once at the boundary in _make_tag; doing
+            # it here too would double-escape (``&`` → ``&`` →
+            # ``&``).
+
+            # Remove double spaces
+            while text.find("  ") != -1:
+                text = text.replace("  ", " ")
+
+            # Put a space between elements if one does not already exist.
+            if (
+                len(self.description) > 0
+                and len(text) > 0
+                and self.description[-1] not in string.whitespace
+                and text[0] not in string.whitespace + string.punctuation
+            ):
+                self.description += " "
+
+            self.description += text
+
+    def dispatch_departure(self, node: nodes.Node) -> None:
+        """Emit separators and enforce the length cap when leaving nodes."""
+        # Separate title from text
+        if isinstance(node, nodes.title):
+            self.description += ":"
+
+        # Separate list elements
+        if isinstance(node, nodes.Part):
+            self.description += ","
+
+        # Separate end of list from text
+        if isinstance(node, nodes.Sequential):
+            if self.description and self.description[-1] == ",":
+                self.description = self.description[:-1]
+            self.description += "."
+            self.list_level -= 1
+
+        # Check for length
+        if len(self.description) > self.desc_len:
+            self.description = self.description[: self.desc_len]
+            if self.desc_len >= 3:
+                self.description = self.description[:-3] + "..."
+
+            self.stop = True

sphinx_gp_opengraph-0.0.1a10/src/sphinx_gp_opengraph/_meta.py

@@ -0,0 +1,59 @@
+"""Detect a pre-existing ``<meta name="description">`` in collected meta tags.
+
+Ported verbatim from ``sphinxext.opengraph._meta_parser`` (v0.13.0), with
+a narrowed return type annotation (upstream declared ``bool`` but actually
+returns ``str | bool | None``).
+
+Examples
+--------
+>>> from sphinx_gp_opengraph._meta import get_meta_description
+>>> get_meta_description('<meta name="description" content="hello">')
+'hello'
+>>> get_meta_description('<meta name="other" content="hi">') is None
+True
+"""
+
+from __future__ import annotations
+
+import html.parser
+
+
+def get_meta_description(meta_tags: str) -> str | bool | None:
+    """Return the ``content`` of an existing description meta tag, if any.
+
+    Parameters
+    ----------
+    meta_tags : str
+        Concatenated ``<meta ...>`` tags (as produced by Sphinx).
+
+    Returns
+    -------
+    str | bool | None
+        The content string when a matching meta tag carries a ``content``
+        attribute; ``True`` when a description tag is present but has no
+        content attribute; ``None`` otherwise.
+    """
+    htp = HTMLTextParser()
+    htp.feed(meta_tags)
+    htp.close()
+
+    return htp.meta_description
+
+
+class HTMLTextParser(html.parser.HTMLParser):
+    """Flag the presence (and content) of a ``<meta name="description">``."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.meta_description: str | bool | None = None
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        """Capture the description content when the matching meta opens."""
+        # For example:
+        # attrs = [("content", "My manual description"), ("name", "description")]
+        if ("name", "description") in attrs:
+            self.meta_description = True
+            for name, value in attrs:
+                if name == "content":
+                    self.meta_description = value
+                    break

sphinx_gp_opengraph-0.0.1a10/src/sphinx_gp_opengraph/_title.py

@@ -0,0 +1,94 @@
+"""Extract plain text from an HTML-formatted Sphinx title.
+
+Ported verbatim from ``sphinxext.opengraph._title_parser`` (v0.13.0).
+
+Examples
+--------
+>>> from sphinx_gp_opengraph._title import get_title
+>>> get_title("<em>libtmux</em>-mcp")
+('libtmux-mcp', '-mcp')
+"""
+
+from __future__ import annotations
+
+import html.parser
+
+
+def get_title(title: str) -> tuple[str, str]:
+    """Return ``(all_text, text_outside_tags)`` parsed from a title string.
+
+    Parameters
+    ----------
+    title : str
+        Title text that may contain HTML markup (e.g. an ``<em>`` span
+        added by a Sphinx transform).
+
+    Returns
+    -------
+    tuple[str, str]
+        Full text (tags stripped) and the subset that appeared outside
+        any HTML tag. The second element is used when a title has been
+        decorated with visual affordances (icons, wrappers) that should
+        be stripped for search-engine metadata.
+    """
+    htp = HTMLTextParser()
+    htp.feed(title)
+    htp.close()
+
+    return htp.text, htp.text_outside_tags
+
+
+_VOID_ELEMENTS = frozenset(
+    {
+        "area",
+        "base",
+        "br",
+        "col",
+        "embed",
+        "hr",
+        "img",
+        "input",
+        "link",
+        "meta",
+        "param",
+        "source",
+        "track",
+        "wbr",
+    },
+)
+
+
+class HTMLTextParser(html.parser.HTMLParser):
+    """Track text-inside-tags vs text-outside-tags while parsing HTML."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        # All text found
+        self.text = ""
+        # Only text outside of html tags
+        self.text_outside_tags = ""
+        self.level = 0
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        """Increase the tag-nesting level (ignoring void elements)."""
+        if tag not in _VOID_ELEMENTS:
+            self.level += 1
+
+    def handle_endtag(self, tag: str) -> None:
+        """Decrease the tag-nesting level (ignoring void elements).
+
+        ``html.parser.HTMLParser`` routes XHTML self-closing forms like
+        ``<br/>`` through ``handle_startendtag``, whose default impl
+        calls both ``handle_starttag`` and ``handle_endtag``. Filtering
+        only the start path would leave the unbalanced end decrement,
+        sending ``self.level`` negative and dropping every subsequent
+        chunk from ``text_outside_tags``.
+        """
+        if tag not in _VOID_ELEMENTS:
+            self.level -= 1
+
+    def handle_data(self, data: str) -> None:
+        """Accumulate text, tracking whether it fell outside any tag."""
+        self.text += data
+        if self.level == 0:
+            self.text_outside_tags += data