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