sphinx-gated-content 0.3.0

Build public and gated versions of Sphinx documentation.

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:

: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

pip install sphinx-gated-content

Quick Start

Enable the extension in your conf.py:

import os

extensions = [
    "sphinx_gated_content",
]

gated_content_public_build = (
    os.getenv("SPHINX_GATED_PUBLIC", "1") == "1"
)

Generate a public build

SPHINX_GATED_PUBLIC=1 \
python -m sphinx -b html docs docs/_build/public

Generate a gated build

SPHINX_GATED_PUBLIC=0 \
python -m sphinx -b html docs docs/_build/gated

Configuration

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."

# Prevent copying source files in public builds
html_copy_source = not gated_content_public_build

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.

Additionally, it automatically:

• Removes the _sources folder (contains original source files)
• Filters objects.inv to remove references to private pages

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:

python -m venv .venv
source .venv/bin/activate

Install dependencies:

python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -e .

Run tests:

python -m pytest

Build the documentation:

python -m sphinx -b html docs docs/_build/html

License

MIT