Metadata-Version: 2.4
Name: sphinx-confluencebuilder-bridge
Version: 2026.10.9
Summary: Extension for Sphinx which enables using directives and roles from Atlassian® Confluence® Builder for Sphinx in other Sphinx builders such as HTML.
Author-email: Adam Dangoor <adamdangoor@gmail.com>
License-Expression: MIT
Project-URL: Source, https://github.com/adamtheturtle/sphinx-confluencebuilder-bridge
Keywords: confluence,documentation,rst,sphinx
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Pytest
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: beartype>=0.22.9
Requires-Dist: docutils>=0.19
Requires-Dist: sphinx<10,>=9
Requires-Dist: sphinx-simplepdf>=1.6.0
Requires-Dist: typing-extensions>=4.4
Dynamic: license-file

|Build Status| |PyPI|

Sphinx Confluence Builder Bridge
================================

Extension for Sphinx which enables using directives and roles from `Atlassian® Confluence® Builder for Sphinx <https://sphinxcontrib-confluencebuilder.readthedocs.io>`_ in other Sphinx builders such as HTML.
This enables you to use HTML builds for easy iteration while developing documentation which is primarily meant for Confluence.

.. contents::

Installation
------------

``sphinx-confluencebuilder-bridge`` is compatible with Python |minimum-python-version|\+.

.. code-block:: console

   $ pip install sphinx-confluencebuilder-bridge

Setup
-----

Add the following to ``conf.py`` to enable the extension:

.. code-block:: python

   """Configuration for Sphinx."""

   extensions = ["sphinxcontrib.confluencebuilder"]  # Example existing extensions

   extensions += [
       # This must come after ``"sphinxcontrib.confluencebuilder"``
       "sphinx_confluencebuilder_bridge"
   ]

Supported directives
--------------------

Only some of the `directives supported by Atlassian® Confluence® Builder for Sphinx <https://sphinxcontrib-confluencebuilder.readthedocs.io/directives>`_ are supported.
The following directives are supported:

* `confluence_toc <https://sphinxcontrib-confluencebuilder.readthedocs.io/en/stable/directives/#directive-confluence_toc>`_
   * The only supported option is `max-level <https://sphinxcontrib-confluencebuilder.readthedocs.io/en/stable/directives/#directive-option-confluence_toc-max-level>`_.

* ``confluence_viewpdf``
   * HTML output builders only (e.g. ``html``, ``dirhtml``, ``singlehtml``).
   * Requires the PDF to be in a directory specified in `html_static_path <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path>`_.

Supported roles
---------------

Only some of the `roles supported by Atlassian® Confluence® Builder for Sphinx <https://sphinxcontrib-confluencebuilder.readthedocs.io/roles>`_ are supported.
The following roles are supported:

* `confluence_link <https://sphinxcontrib-confluencebuilder.readthedocs.io/en/stable/roles/#role-confluence_link>`_
   * This renders as a normal hyperlink, unlike in Confluence where the page title is shown.
* `confluence_doc <https://sphinxcontrib-confluencebuilder.readthedocs.io/en/stable/roles/#role-confluence_doc>`_
   * This renders as a normal documentation link, unlike in Confluence where the page title is shown.
* `confluence_mention <https://sphinxcontrib-confluencebuilder.readthedocs.io/en/stable/roles/#role-confluence_mention>`_
   * This renders as a link with the text being the user's account identifier, user key or username.
   * For this to show a clear account identifier, set `confluence_mentions <https://sphinxcontrib-confluencebuilder.readthedocs.io/en/stable/configuration/#confval-confluence_mentions>`_ in ``conf.py``.

Contributing
------------

See `CONTRIBUTING.rst <./CONTRIBUTING.rst>`_.

.. |Build Status| image:: https://github.com/adamtheturtle/sphinx-confluencebuilder-bridge/actions/workflows/ci.yml/badge.svg?branch=main
   :target: https://github.com/adamtheturtle/sphinx-confluencebuilder-bridge/actions
.. |PyPI| image:: https://badge.fury.io/py/sphinx-confluencebuilder-bridge.svg
   :target: https://badge.fury.io/py/sphinx-confluencebuilder-bridge
.. |minimum-python-version| replace:: 3.11
