Sphinx Confluence Builder

Warnings

• breaking The default editor for Confluence Cloud switched from 'v1' to 'v2' in version 3.0. Users with custom configurations relying on 'v1' might experience rendering issues.
  Fix: Review Confluence page rendering post-upgrade. If issues occur, adjust content or set `confluence_editor = 'v1'` in `conf.py` if 'v1' is still supported by your Confluence instance and desired.
• breaking All deprecated configuration options from 2.x and older versions were completely removed in version 3.0. This includes the `confluence_editor` option being deprecated.
  Fix: Consult the latest documentation for equivalent or new configuration options. Replace any removed options. For `confluence_editor`, consider if `v2` is acceptable or if `confluence_cloud` and `confluence_publish_token` options provide necessary alternatives for modern Confluence environments.
• breaking Support for Python 3.9 was dropped starting with version 2.16 (with v2.15 being the final release to support it).
  Fix: Upgrade your Python environment to 3.10 or newer to use versions 2.16+ of `sphinxcontrib-confluencebuilder`.
• deprecated The `confluence_asset_force_standalone` option was removed in version 2.15 as assets are now always standalone. Page-specific editor overrides were also deprecated in version 2.14.
  Fix: Remove `confluence_asset_force_standalone` from your `conf.py` as its behavior is now default. Avoid using page-specific editor overrides and transition to global or builder-specific configurations if possible.
• gotcha It is never recommended to store sensitive authentication information (API tokens or raw passwords) directly in a committed repository.
  Fix: Use environment variables (e.g., `os.environ.get('CONFLUENCE_PUBLISH_TOKEN')`), a secure credential manager, or prompt for credentials at build time (e.g., `confluence_ask_password = True`) to keep secrets out of source control.

Install

• pip install sphinxcontrib-confluencebuilder Install latest version

Imports

• sphinxcontrib.confluencebuilder

  extensions = ['sphinxcontrib.confluencebuilder'] # in conf.py

  This library is a Sphinx extension; it is activated by adding its name to the 'extensions' list in your Sphinx project's conf.py, not by a direct Python import statement in application code.

Quickstart

To quickly get started, add `sphinxcontrib.confluencebuilder` to the `extensions` list in your Sphinx project's `conf.py`. Then, configure the essential publishing options, including your Confluence server URL, space key, and authentication credentials (preferably an API token via environment variable). Finally, execute Sphinx with the `confluence` builder to generate and publish your documentation.

import os

# --- In conf.py ---

# Add 'sphinxcontrib.confluencebuilder' to your extensions list
extensions = [
    'sphinxcontrib.confluencebuilder'
]

# --- Essential Confluence Publishing Configuration ---
# Ensure these are set to enable publishing to Confluence
confluence_publish = True
confluence_space_key = os.environ.get('CONFLUENCE_SPACE_KEY', 'MYSPACE') # Use your Confluence space key
confluence_parent_page = os.environ.get('CONFLUENCE_PARENT_PAGE', 'MyDocumentation') # Top-level page under which docs will be published
confluence_server_url = os.environ.get('CONFLUENCE_SERVER_URL', 'https://example.atlassian.net/wiki/') # Your Confluence URL
confluence_server_user = os.environ.get('CONFLUENCE_SERVER_USER', 'myuser@example.com') # Your Confluence username (email for Cloud)

# Using an API token is highly recommended instead of a password.
# Store securely, e.g., in an environment variable.
# For Confluence Cloud, use confluence_publish_token for API tokens.
# For Data Center, confluence_server_pass can be used for password or PAT.
confluence_publish_token = os.environ.get('CONFLUENCE_PUBLISH_TOKEN', '')

# Optional: Enable dry run to check what would be published without actually publishing
# confluence_publish_dryrun = True


# --- To build and publish from your project root (after conf.py is setup) ---
# Run in your terminal:
# sphinx-build -M confluence . _build -E -a
# or
# python -m sphinx -M confluence . _build -E -a