Metadata-Version: 2.5
Name: sphinx-gated-content
Version: 0.4.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
```

### Clearing the build cache

When switching between public and gated builds or changing builders, clear the cache to ensure gating is correctly applied:

```bash
rm -rf docs/_build
```

Sphinx caches parsed doctrees by builder. If you don't clear the cache when switching build modes or builders, cached doctrees from previous builds may be reused, causing gating to not apply correctly (especially for LaTeX builds).

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

# 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

The public/gated page filtering also applies to LaTeX output, which can be
compiled to PDF with a TeX distribution. Lock icons and HTML-specific output
cleanup do not apply to LaTeX/PDF builds.

## 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:

- 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