Sphinx Extension: Feature Flags

Description

This Sphinx extension allows for the feature-flag directive to show (if True) or fallback (if False and using the :fallback: option).

Setup

Add the following to your conf.py:

import sys, os

sys.path.append(os.path.abspath(os.path.join('_extensions', 'sphinx_feature_flags')))
extensions = ['sphinx_feature_flags']

feature_flags = {
    'production-stage': False,  # Example
}

Usage

In any .rst file, wrap the feature-flag directive around any block:

```rst
.. feature-flag:: dev-debug-mode

   This only shows if production-stage = True; it can be an entire toctree, too!

.. feature-flag:: dev-debug-mode
   :fallback:

   This only shows if production-stage = False.
```

Requirements

Python>=3.6
Sphinx>=1.8

This may work with older versions, but has not been tested.

Entry Point

See setup(app) definition at sphinx_feature_flags.py.

Tested in

Windows 11 via PowerShell 7
Ubuntu 22.04 via ReadTheDocs (RTD) CI

Notes

__init__.py is required for both external pathing and to treat the directory as a pkg

Metadata

Release files for sphinx-feature-flags 1.0.9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sphinx-feature-flags 1.0.9
File	Size	Uploaded
sphinx_feature_flags-1.0.9.tar.gz	3.3 kB	Jan 3, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for sphinx-feature-flags 1.0.9
File	Interpreter	ABI	Platform	Reset
sphinx_feature_flags-1.0.9-py3-none-any.whl 4.0 kB Jan 3, 2025	Python 3	none	any	Details

Total release size: 7.3 kB

Release files / sphinx_feature_flags-1.0.9.tar.gz

Download URL	sphinx_feature_flags-1.0.9.tar.gz
Size	3.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`1f0c7450d5f19abda016deb0e8a928d81c601b368775f32f0258e4ec98605721`
BLAKE2b-256 checksum How to use checksums	`6c8026a78a8d4e8e0a7d959f73d0034814057322dd9450632ccb1deaf7a26129`
Upload date	Jan 3, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.0.1 CPython/3.10.16`

Release files / sphinx_feature_flags-1.0.9-py3-none-any.whl

Download URL	sphinx_feature_flags-1.0.9-py3-none-any.whl
Size	4.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`e1f601afe98cb4ed1686ecafdf545dafa5ebf0ecb58a85f41b4acb15b374877c`
BLAKE2b-256 checksum How to use checksums	`f6fae361a1acd20b46a31286a53e5138afd0df8dcccf7bd1f1ef3d01cf563eb6`
Upload date	Jan 3, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.0.1 CPython/3.10.16`