sphinx-gated-content 0.1.0__tar.gz

sphinx_gated_content-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,72 @@
+name: Publish to PyPI and Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+
+      - name: Install build
+        run: python -m pip install --upgrade build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Store distributions
+        uses: actions/upload-artifact@v5
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v5
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v5
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Create release and upload distributions
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

sphinx_gated_content-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+
+# Virtual envs
+.venv/
+venv/
+
+# Packaging
+build/
+dist/
+*.egg-info/
+
+# Test
+.pytest_cache/
+.coverage
+
+# Docs
+docs/_build/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

sphinx_gated_content-0.1.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows Semantic Versioning.
+
+## [0.1.0] - 2026-06-07
+
+### Added
+
+- Mark documentation pages as gated using page metadata:
+
+  ```rst
+  :private: true
+  ```
+
+- Generate two documentation variants from the same source tree:
+  - **Public build**: gated pages are replaced with a configurable placeholder.
+  - **Gated build**: all pages are rendered normally.
+
+- Configurable placeholder text for gated pages.
+
+- Configurable metadata key used to identify gated content.
+
+- Configurable lock icon for gated pages.
+
+- Removal of gated page content from public HTML output.
+
+- Removal of gated page content from the generated search index.
+
+- Sidebar lock indicators for supported themes.
+
+### Supported themes
+
+- Alabaster
+- Read the Docs Theme (`sphinx_rtd_theme`)
+- Shibuya
+
+### Tested with
+
+- Python 3.9+
+- Sphinx 7+

sphinx_gated_content-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Accelerat S.r.l.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sphinx_gated_content-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: sphinx-gated-content
+Version: 0.1.0
+Summary: Build public and gated versions of Sphinx documentation.
+Project-URL: Homepage, https://github.com/accelerat-team/sphinx-gated-content
+Project-URL: Repository, https://github.com/accelerat-team/sphinx-gated-content
+Project-URL: Issues, https://github.com/accelerat-team/sphinx-gated-content/issues
+Project-URL: Company, https://accelerat.eu
+Author: Gabriele Serra
+License-Expression: MIT
+License-File: LICENSE
+Keywords: docs,documentation,gated-content,sphinx,subscriptions
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Sphinx
+Classifier: Framework :: Sphinx :: Extension
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Requires-Dist: sphinx>=7.0
+Provides-Extra: docs
+Requires-Dist: shibuya; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme>=3; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: beautifulsoup4>=4.12; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: shibuya; extra == 'test'
+Requires-Dist: sphinx-rtd-theme>=3; extra == 'test'
+Description-Content-Type: text/markdown
+
+# sphinx-gated-content
+
+Build **public** and **gated** versions of your Sphinx documentation from the same source tree.
+
+`sphinx-gated-content` allows you to mark pages as private and generate two different documentation builds:
+
+| Build | Visible content |
+|---------|---------|
+| **Public** | Public pages + placeholders for gated pages |
+| **Gated** | All pages, including gated content |
+
+This is useful for:
+
+- Subscription-based documentation
+- Freemium products
+- Internal vs public documentation
+- Community vs enterprise documentation
+- Documentation previews
+
+## How it works
+
+Mark a page as private:
+
+```rst
+:private: true
+
+Advanced API
+============
+
+This content is subscription-only.
+```
+
+Then choose which build to generate.
+
+### Public build
+
+Private pages remain visible in the navigation but:
+
+- display a lock icon (`🔒`)
+- show a placeholder page instead of the real content
+- are removed from the search index
+
+### Gated build
+
+All pages are rendered normally.
+
+No content is removed or replaced.
+
+## Installation
+
+```bash
+pip install sphinx-gated-content
+```
+
+## Quick Start
+
+Enable the extension in your `conf.py`:
+
+```python
+import os
+
+extensions = [
+    "sphinx_gated_content",
+]
+
+gated_content_public_build = (
+    os.getenv("SPHINX_GATED_PUBLIC", "1") == "1"
+)
+```
+
+### Generate a public build
+
+```bash
+SPHINX_GATED_PUBLIC=1 \
+python -m sphinx -b html docs docs/_build/public
+```
+
+### Generate a gated build
+
+```bash
+SPHINX_GATED_PUBLIC=0 \
+python -m sphinx -b html docs docs/_build/gated
+```
+
+## Configuration
+
+```python
+gated_content_public_build = True
+gated_content_private_metadata_key = "private"
+gated_content_lock_icon = "🔒"
+gated_content_placeholder = "This page is available with a subscription."
+```
+
+## Supported Themes
+
+Currently tested with:
+
+- Alabaster
+- Read the Docs Theme (`sphinx_rtd_theme`)
+- Shibuya
+
+## Security
+
+`sphinx-gated-content` removes gated page content from public HTML builds and excludes it from the generated search index.
+
+You should still verify any additional build outputs you publish, such as:
+
+- PDFs
+- EPUB files
+- downloadable source archives
+- custom builders
+- static assets generated by third-party extensions
+
+## Development
+
+Create a virtual environment:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+Install dependencies:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt
+python -m pip install -e .
+```
+
+Run tests:
+
+```bash
+python -m pytest
+```
+
+Build the documentation:
+
+```bash
+python -m sphinx -b html docs docs/_build/html
+```
+
+## License
+
+MIT

sphinx_gated_content-0.1.0/README.md

@@ -0,0 +1,145 @@
+# sphinx-gated-content
+
+Build **public** and **gated** versions of your Sphinx documentation from the same source tree.
+
+`sphinx-gated-content` allows you to mark pages as private and generate two different documentation builds:
+
+| Build | Visible content |
+|---------|---------|
+| **Public** | Public pages + placeholders for gated pages |
+| **Gated** | All pages, including gated content |
+
+This is useful for:
+
+- Subscription-based documentation
+- Freemium products
+- Internal vs public documentation
+- Community vs enterprise documentation
+- Documentation previews
+
+## How it works
+
+Mark a page as private:
+
+```rst
+:private: true
+
+Advanced API
+============
+
+This content is subscription-only.
+```
+
+Then choose which build to generate.
+
+### Public build
+
+Private pages remain visible in the navigation but:
+
+- display a lock icon (`🔒`)
+- show a placeholder page instead of the real content
+- are removed from the search index
+
+### Gated build
+
+All pages are rendered normally.
+
+No content is removed or replaced.
+
+## Installation
+
+```bash
+pip install sphinx-gated-content
+```
+
+## Quick Start
+
+Enable the extension in your `conf.py`:
+
+```python
+import os
+
+extensions = [
+    "sphinx_gated_content",
+]
+
+gated_content_public_build = (
+    os.getenv("SPHINX_GATED_PUBLIC", "1") == "1"
+)
+```
+
+### Generate a public build
+
+```bash
+SPHINX_GATED_PUBLIC=1 \
+python -m sphinx -b html docs docs/_build/public
+```
+
+### Generate a gated build
+
+```bash
+SPHINX_GATED_PUBLIC=0 \
+python -m sphinx -b html docs docs/_build/gated
+```
+
+## Configuration
+
+```python
+gated_content_public_build = True
+gated_content_private_metadata_key = "private"
+gated_content_lock_icon = "🔒"
+gated_content_placeholder = "This page is available with a subscription."
+```
+
+## Supported Themes
+
+Currently tested with:
+
+- Alabaster
+- Read the Docs Theme (`sphinx_rtd_theme`)
+- Shibuya
+
+## Security
+
+`sphinx-gated-content` removes gated page content from public HTML builds and excludes it from the generated search index.
+
+You should still verify any additional build outputs you publish, such as:
+
+- PDFs
+- EPUB files
+- downloadable source archives
+- custom builders
+- static assets generated by third-party extensions
+
+## Development
+
+Create a virtual environment:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+Install dependencies:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt
+python -m pip install -e .
+```
+
+Run tests:
+
+```bash
+python -m pytest
+```
+
+Build the documentation:
+
+```bash
+python -m sphinx -b html docs docs/_build/html
+```
+
+## License
+
+MIT

sphinx_gated_content-0.1.0/docs/conf.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "src"
+
+sys.path.insert(0, str(SRC))
+
+project = "sphinx-gated-content"
+author = "Gabriele Serra"
+copyright = "2026, Accelerat"
+
+extensions = [
+    "sphinx_gated_content",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_title = "sphinx-gated-content"
+
+gated_content_public_build = os.getenv("SPHINX_GATED_PUBLIC", "1") == "1"
+gated_content_private_metadata_key = "private"
+gated_content_lock_icon = "🔒"
+gated_content_placeholder = "This page is available with a subscription."
+
+html_theme = os.getenv("SPHINX_THEME", "alabaster")

sphinx_gated_content-0.1.0/docs/examples.rst

@@ -0,0 +1,41 @@
+Examples
+========
+
+Public page
+-----------
+
+This page is public and appears normally in both public and gated builds.
+
+Private page
+------------
+
+A private page can be written like this:
+
+.. code-block:: rst
+
+   :private: true
+
+   Advanced Tutorial
+   =================
+
+   This content is visible only in the gated build.
+
+Custom metadata key
+-------------------
+
+You can use a different metadata key:
+
+.. code-block:: python
+
+   gated_content_private_metadata_key = "gated_only"
+
+Then mark pages like this:
+
+.. code-block:: rst
+
+   :gated_only: true
+
+   Enterprise Guide
+   ================
+
+   This content is subscription-only.

sphinx_gated_content-0.1.0/docs/index.rst

@@ -0,0 +1,14 @@
+sphinx-gated-content
+=====================
+
+Build public and "gated" versions of Sphinx documentation from the same source
+tree.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   usage
+   examples
+   public_page
+   private_page

sphinx_gated_content-0.1.0/docs/private_page.rst

@@ -0,0 +1,6 @@
+:private: true
+
+Private Page
+============
+
+This content should only appear in gated builds.

sphinx_gated_content-0.1.0/docs/public_page.rst

@@ -0,0 +1,4 @@
+Public Page
+===========
+
+This page should always be visible.

sphinx_gated_content-0.1.0/docs/usage.rst

@@ -0,0 +1,54 @@
+Usage
+=====
+
+Enable the extension in your Sphinx ``conf.py``:
+
+.. code-block:: python
+
+   import os
+
+   extensions = [
+       "sphinx_gated_content",
+   ]
+
+   gated_content_public_build = os.getenv("SPHINX_GATED_PUBLIC", "1") == "1"
+
+Mark private pages with reStructuredText metadata:
+
+.. code-block:: rst
+
+   :private: true
+
+   Advanced API
+   ============
+
+   This page is subscription-only.
+
+Public builds
+-------------
+
+In public builds, private pages remain part of the documentation structure, but
+their content is replaced with a placeholder.
+
+.. code-block:: bash
+
+   SPHINX_GATED_PUBLIC=1 sphinx-build -b html docs docs/_build/public
+
+Gated builds
+-------------
+
+In gated builds, private pages are rendered normally.
+
+.. code-block:: bash
+
+   SPHINX_GATED_PUBLIC=0 sphinx-build -b html docs docs/_build/gated
+
+Configuration
+-------------
+
+.. code-block:: python
+
+   gated_content_public_build = True
+   gated_content_private_metadata_key = "private"
+   gated_content_lock_icon = "🔒"
+   gated_content_placeholder = "This page is available with a subscription."

sphinx_gated_content-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sphinx-gated-content"
+version = "0.1.0"
+description = "Build public and gated versions of Sphinx documentation."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+
+authors = [
+  { name = "Gabriele Serra" }
+]
+
+keywords = [
+  "sphinx",
+  "documentation",
+  "docs",
+  "gated-content",
+  "subscriptions",
+]
+
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: Sphinx",
+  "Framework :: Sphinx :: Extension",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+
+dependencies = [
+  "sphinx>=7.0",
+]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8",
+  "beautifulsoup4>=4.12",
+  "sphinx-rtd-theme>=3",
+  "shibuya",
+]
+
+docs = [
+  "sphinx-rtd-theme>=3",
+  "shibuya",
+]
+
+[project.urls]
+Homepage = "https://github.com/accelerat-team/sphinx-gated-content"
+Repository = "https://github.com/accelerat-team/sphinx-gated-content"
+Issues = "https://github.com/accelerat-team/sphinx-gated-content/issues"
+Company = "https://accelerat.eu"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sphinx_gated_content-0.1.0/requirements.txt

@@ -0,0 +1,8 @@
+sphinx>=7.0
+pytest>=8.0
+beautifulsoup4>=4.12
+sphinx-rtd-theme>=3.0
+shibuya>=2026.5
+
+build>=1.2
+twine>=6.0

sphinx_gated_content-0.1.0/src/sphinx_gated_content/__init__.py

@@ -0,0 +1,4 @@
+"""Sphinx extension for building public and gated documentation variants."""
+from .extension import setup
+
+__all__ = ["setup"]

sphinx_gated_content-0.1.0/src/sphinx_gated_content/constants.py

@@ -0,0 +1,17 @@
+"""Constants used by sphinx-gated-content."""
+
+# Configuration variables used to control the configuration of this extension
+CONFIG_PUBLIC_BUILD = "gated_content_public_build"
+CONFIG_PRIVATE_METADATA_KEY = "gated_content_private_metadata_key"
+CONFIG_LOCK_ICON = "gated_content_lock_icon"
+CONFIG_PLACEHOLDER = "gated_content_placeholder"
+
+# Default values assigned to configuration variables
+DEFAULT_PUBLIC_BUILD = True
+DEFAULT_PRIVATE_METADATA_KEY = "private"
+DEFAULT_LOCK_ICON = "🔒"
+DEFAULT_PLACEHOLDER = "This page is available with a subscription."
+
+# Miscellaneous
+PRIVATE_PAGES_ATTR = "gated_content_private_pages"
+DEFAULT_FALLBACK_TITLE = "Gated content"

sphinx_gated_content-0.1.0/src/sphinx_gated_content/extension.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from sphinx.application import Sphinx
+
+from .metadata import collect_private_pages
+from .transforms import replace_private_page_content
+from .html import add_lock_context
+from .constants import (
+    CONFIG_LOCK_ICON,
+    CONFIG_PLACEHOLDER,
+    CONFIG_PRIVATE_METADATA_KEY,
+    CONFIG_PUBLIC_BUILD,
+    DEFAULT_LOCK_ICON,
+    DEFAULT_PLACEHOLDER,
+    DEFAULT_PRIVATE_METADATA_KEY,
+    DEFAULT_PUBLIC_BUILD,
+)
+
+def _package_version() -> str:
+    """Return the installed package version."""
+    try:
+        return version("sphinx-gated-content")
+    except PackageNotFoundError:
+        return "0.0.0"
+
+
+def setup(app: Sphinx) -> dict[str, object]:
+    """Register the sphinx-gated-content extension with Sphinx."""
+    app.add_config_value(CONFIG_PUBLIC_BUILD, DEFAULT_PUBLIC_BUILD, 'env')
+    app.add_config_value(
+        CONFIG_PRIVATE_METADATA_KEY,
+        DEFAULT_PRIVATE_METADATA_KEY,
+        'env',
+    )
+    app.add_config_value(CONFIG_LOCK_ICON, DEFAULT_LOCK_ICON, 'html')
+    app.add_config_value(CONFIG_PLACEHOLDER, DEFAULT_PLACEHOLDER, 'html')
+
+    app.connect("doctree-read", collect_private_pages)
+    app.connect("doctree-resolved", replace_private_page_content)
+    app.connect("html-page-context", add_lock_context)
+
+    return {
+        "version": _package_version(),
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

sphinx_gated_content-0.1.0/src/sphinx_gated_content/html.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from html import escape
+from typing import Any
+
+from .constants import CONFIG_LOCK_ICON, CONFIG_PUBLIC_BUILD, PRIVATE_PAGES_ATTR
+
+HREF_RE = re.compile(
+    r'(<a\b[^>]*\bhref=["\'](?P<href>[^"\']+)["\'][^>]*>)'
+    r'(?P<label>.*?)'
+    r'(</a>)',
+    re.IGNORECASE | re.DOTALL,
+)
+
+TOC_CONTEXT_KEYS = (
+    "toctree",
+    "generate_toctree_html",
+    "toc",
+)
+
+
+def _docname_from_href(href: str) -> str:
+    """Convert a generated HTML link into a Sphinx docname-like path."""
+    href = href.split("#", 1)[0].split("?", 1)[0].strip()
+
+    if not href or href.startswith(("http://", "https://", "mailto:")):
+        return ""
+
+    href = href.lstrip("./")
+
+    while href.startswith("../"):
+        href = href[3:]
+
+    if href.endswith("/"):
+        href = f"{href}index.html"
+
+    if href.endswith(".html"):
+        href = href[:-5]
+
+    return href.strip("/")
+
+
+def _doc_matches_private_page(docname: str, private_pages: set[str]) -> bool:
+    """Return whether a docname corresponds to a gated page."""
+    if docname in private_pages:
+        return True
+
+    if docname.endswith("/index"):
+        return docname[:-6] in private_pages
+
+    return False
+
+
+def _inject_locks(html: str, app) -> str:
+    """Add lock icons to links pointing to gated pages in public builds."""
+    if not getattr(app.config, CONFIG_PUBLIC_BUILD):
+        return html
+
+    private_pages = set(getattr(app.env, PRIVATE_PAGES_ATTR, set()))
+    if not private_pages:
+        return html
+
+    icon = escape(getattr(app.config, CONFIG_LOCK_ICON))
+
+    def replace(match: re.Match[str]) -> str:
+        href = match.group("href")
+        label = match.group("label")
+        docname = _docname_from_href(href)
+
+        if not _doc_matches_private_page(docname, private_pages):
+            return match.group(0)
+
+        if icon in label:
+            return match.group(0)
+
+        return f"{match.group(1)}{label} {icon}{match.group(4)}"
+
+    return HREF_RE.sub(replace, html)
+
+
+def _wrap_html_function(func: Callable[..., str], app) -> Callable[..., str]:
+    """Wrap a Sphinx context function and inject locks into its HTML output."""
+
+    def wrapped(*args: Any, **kwargs: Any) -> str:
+        return _inject_locks(func(*args, **kwargs), app)
+
+    return wrapped
+
+
+def add_lock_context(app, pagename, templatename, context, doctree) -> None:
+    """Expose gated-content context values and patch sidebar TOC HTML."""
+    private_pages = set(getattr(app.env, PRIVATE_PAGES_ATTR, set()))
+
+    context["gated_content_private_pages"] = private_pages
+    context["gated_content_is_private"] = pagename in private_pages
+    context["gated_content_lock_icon"] = getattr(app.config, CONFIG_LOCK_ICON)
+    context["gated_content_public_build"] = getattr(app.config, CONFIG_PUBLIC_BUILD)
+
+    for key in TOC_CONTEXT_KEYS:
+        value = context.get(key)
+
+        if callable(value):
+            context[key] = _wrap_html_function(value, app)
+        elif isinstance(value, str):
+            context[key] = _inject_locks(value, app)

sphinx_gated_content-0.1.0/src/sphinx_gated_content/metadata.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .constants import CONFIG_PRIVATE_METADATA_KEY, PRIVATE_PAGES_ATTR
+
+TRUE_VALUES: set[str] = {
+    "1",
+    "true",
+    "yes",
+    "on",
+}
+
+def is_truthy(value: Any) -> bool:
+    """Return whether a metadata value should be treated as enabled."""
+    return str(value).strip().lower() in TRUE_VALUES
+
+def collect_private_pages(app, doctree) -> None:
+    """Collect document names marked as gated through page metadata."""
+    docname = app.env.docname
+    key = getattr(app.config, CONFIG_PRIVATE_METADATA_KEY)
+
+    metadata = app.env.metadata.get(docname, {})
+    is_private = is_truthy(metadata.get(key))
+
+    if not hasattr(app.env, PRIVATE_PAGES_ATTR):
+        setattr(app.env, PRIVATE_PAGES_ATTR, set())
+
+    private_pages = getattr(app.env, PRIVATE_PAGES_ATTR)
+
+    if is_private:
+        private_pages.add(docname)

sphinx_gated_content-0.1.0/src/sphinx_gated_content/transforms.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from docutils import nodes
+
+from .constants import (
+    CONFIG_PLACEHOLDER,
+    CONFIG_PUBLIC_BUILD,
+    DEFAULT_PLACEHOLDER,
+    DEFAULT_FALLBACK_TITLE,
+    PRIVATE_PAGES_ATTR,
+)
+
+def _page_title(doctree) -> str:
+    """Return the page title from the doctree, or a safe fallback."""
+    title = doctree.next_node(nodes.title)
+
+    if title is None:
+        return DEFAULT_FALLBACK_TITLE
+
+    return title.astext()
+
+
+def replace_private_page_content(app, doctree, docname: str) -> None:
+    """Replace gated page content with a placeholder in public builds."""
+    if not getattr(app.config, CONFIG_PUBLIC_BUILD):
+        return
+
+    private_pages = getattr(app.env, PRIVATE_PAGES_ATTR, set())
+
+    if docname not in private_pages:
+        return
+
+    title_text = _page_title(doctree)
+    placeholder = getattr(app.config, CONFIG_PLACEHOLDER, DEFAULT_PLACEHOLDER)
+
+    doctree.clear()
+
+    section = nodes.section(ids=["gated-content"])
+    section += nodes.title(text=title_text)
+    section += nodes.paragraph(text=placeholder)
+
+    doctree += section

sphinx_gated_content-0.1.0/tests/conftest.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import pytest
+from pathlib import Path
+from sphinx.testing.util import SphinxTestApp
+
+PRIVATE_BODY = "This content is private and should not appear in public builds."
+PRIVATE_SEARCH_TOKEN = "PRIVATE_UNIQUE_SEARCH_TOKEN_12345"
+
+@pytest.fixture()
+def sphinx_project(tmp_path: Path) -> Path:
+    srcdir = tmp_path / "src"
+    srcdir.mkdir()
+
+    (srcdir / "conf.py").write_text(
+        """
+extensions = ["sphinx_gated_content"]
+
+master_doc = "index"
+project = "Test Project"
+
+gated_content_private_metadata_key = "private"
+gated_content_lock_icon = "🔒"
+gated_content_placeholder = "Subscribe to read this page."
+""".strip(),
+        encoding="utf-8",
+    )
+
+    (srcdir / "index.rst").write_text(
+        """
+Test Project
+============
+
+.. toctree::
+   :maxdepth: 2
+
+   public
+   private
+""".strip(),
+        encoding="utf-8",
+    )
+
+    (srcdir / "public.rst").write_text(
+        """
+Public Page
+===========
+
+This content is public.
+""".strip(),
+        encoding="utf-8",
+    )
+
+    (srcdir / "private.rst").write_text(
+        f"""
+:private: true
+
+Private Page
+============
+
+{PRIVATE_BODY}
+
+{PRIVATE_SEARCH_TOKEN}
+""".strip(),
+        encoding="utf-8",
+    )
+
+    return srcdir
+
+
+def build_sphinx(
+    srcdir: Path,
+    *,
+    public: bool,
+    theme: str = "alabaster",
+) -> SphinxTestApp:
+    """Build a temporary Sphinx project for extension tests."""
+    confoverrides = {
+        "html_theme": theme,
+        "gated_content_public_build": public,
+    }
+
+    app = SphinxTestApp(
+        buildername="html",
+        srcdir=srcdir,
+        confoverrides=confoverrides,
+    )
+    app.build()
+    return app
+
+
+@pytest.fixture()
+def public_app(sphinx_project: Path) -> SphinxTestApp:
+    app = build_sphinx(sphinx_project, public=True)
+    yield app
+    app.cleanup()
+
+
+@pytest.fixture()
+def gated_app(sphinx_project: Path) -> SphinxTestApp:
+    app = build_sphinx(sphinx_project, public=False)
+    yield app
+    app.cleanup()

sphinx_gated_content-0.1.0/tests/test_gated_build.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from tests.conftest import PRIVATE_BODY
+
+def test_gated_build_keeps_private_content(gated_app):
+    html = (gated_app.outdir / "private.html").read_text(encoding="utf-8")
+
+    assert "Private Page" in html
+    assert PRIVATE_BODY in html
+    assert "Subscribe to read this page." not in html

sphinx_gated_content-0.1.0/tests/test_import.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+
+def test_extension_imports():
+    import sphinx_gated_content
+
+    assert sphinx_gated_content.setup is not None

sphinx_gated_content-0.1.0/tests/test_private_metadata.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+
+def test_private_page_is_collected(public_app):
+    private_pages = getattr(public_app.env, "gated_content_private_pages", set())
+
+    assert "private" in private_pages
+    assert "public" not in private_pages

sphinx_gated_content-0.1.0/tests/test_public_build.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+def test_public_build_replaces_private_content(public_app):
+    html = (public_app.outdir / "private.html").read_text(encoding="utf-8")
+
+    assert "Private Page" in html
+    assert "Subscribe to read this page." in html
+    assert "This content is private and should not appear" not in html
+
+
+def test_public_build_keeps_public_content(public_app):
+    html = (public_app.outdir / "public.html").read_text(encoding="utf-8")
+
+    assert "Public Page" in html
+    assert "This content is public." in html

sphinx_gated_content-0.1.0/tests/test_search_index.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from tests.conftest import PRIVATE_SEARCH_TOKEN
+
+def test_private_content_not_in_search_index_for_public_build(public_app):
+    searchindex = (
+        public_app.outdir / "searchindex.js"
+    ).read_text(encoding="utf-8")
+
+    assert PRIVATE_SEARCH_TOKEN.lower() not in searchindex.lower()
+
+
+def test_private_content_in_search_index_for_gated_build(gated_app):
+    searchindex = (
+        gated_app.outdir / "searchindex.js"
+    ).read_text(encoding="utf-8")
+
+    assert PRIVATE_SEARCH_TOKEN.lower() in searchindex.lower()

sphinx_gated_content-0.1.0/tests/test_sidebar_lock_themes.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import pytest
+
+from tests.conftest import build_sphinx
+
+
+THEMES = [
+    "alabaster",
+    "sphinx_rtd_theme",
+    "shibuya",
+]
+
+
+@pytest.mark.parametrize("theme", THEMES)
+def test_public_build_adds_lock_to_sidebar_for_theme(
+    sphinx_project,
+    theme,
+):
+    app = build_sphinx(sphinx_project, public=True, theme=theme)
+
+    try:
+        html = (app.outdir / "index.html").read_text(encoding="utf-8")
+
+        assert "Private Page" in html
+        assert "🔒" in html
+    finally:
+        app.cleanup()
+
+
+@pytest.mark.parametrize("theme", THEMES)
+def test_gated_build_does_not_add_lock_to_sidebar_for_theme(
+    sphinx_project,
+    theme,
+):
+    app = build_sphinx(sphinx_project, public=False, theme=theme)
+
+    try:
+        html = (app.outdir / "index.html").read_text(encoding="utf-8")
+
+        assert "Private Page" in html
+        assert "🔒" not in html
+    finally:
+        app.cleanup()

sphinx_gated_content-0.1.0/tests/test_theme_matrix.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import pytest
+
+from tests.conftest import build_sphinx, PRIVATE_BODY, PRIVATE_SEARCH_TOKEN
+
+THEMES = [
+    "alabaster",
+    "sphinx_rtd_theme",
+    "shibuya",
+]
+
+@pytest.mark.parametrize("theme", THEMES)
+@pytest.mark.parametrize("public", [True, False])
+def test_private_page_behavior_across_themes(
+    sphinx_project,
+    theme,
+    public,
+):
+    app = build_sphinx(
+        sphinx_project,
+        public=public,
+        theme=theme,
+    )
+
+    try:
+        private_html = (
+            app.outdir / "private.html"
+        ).read_text(encoding="utf-8")
+
+        searchindex = (
+            app.outdir / "searchindex.js"
+        ).read_text(encoding="utf-8")
+
+        index_html = (
+            app.outdir / "index.html"
+        ).read_text(encoding="utf-8")
+
+        if public:
+            assert "Subscribe to read this page." in private_html
+            assert PRIVATE_BODY not in private_html
+            assert PRIVATE_SEARCH_TOKEN.lower() not in searchindex.lower()
+            assert "🔒" in index_html
+        else:
+            assert "Subscribe to read this page." not in private_html
+            assert PRIVATE_BODY in private_html
+            assert PRIVATE_SEARCH_TOKEN.lower() in searchindex.lower()
+            assert "🔒" not in index_html
+
+    finally:
+        app.cleanup()