Metadata-Version: 2.4
Name: sphinx-confluencebuilder-bridge
Version: 2026.1.12
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
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>=8.2.3
Requires-Dist: sphinx-simplepdf>=1.6.0
Provides-Extra: dev
Requires-Dist: actionlint-py==1.7.10.24; extra == "dev"
Requires-Dist: check-manifest==0.51; extra == "dev"
Requires-Dist: deptry==0.24.0; extra == "dev"
Requires-Dist: doc8==2.0.0; extra == "dev"
Requires-Dist: doccmd==2026.1.3.2; extra == "dev"
Requires-Dist: docformatter==1.7.7; extra == "dev"
Requires-Dist: furo==2025.12.19; extra == "dev"
Requires-Dist: interrogate==1.7.0; extra == "dev"
Requires-Dist: mypy[faster-cache]==1.19.1; extra == "dev"
Requires-Dist: mypy-strict-kwargs==2025.4.3; extra == "dev"
Requires-Dist: myst-parser==4.0.1; extra == "dev"
Requires-Dist: prek==0.2.27; extra == "dev"
Requires-Dist: pylint[spelling]==4.0.4; extra == "dev"
Requires-Dist: pyproject-fmt==2.11.1; extra == "dev"
Requires-Dist: pyrefly==0.47.0; extra == "dev"
Requires-Dist: pyright==1.1.408; extra == "dev"
Requires-Dist: pyroma==5.0.1; extra == "dev"
Requires-Dist: pytest==9.0.2; extra == "dev"
Requires-Dist: pytest-cov==7.0.0; extra == "dev"
Requires-Dist: reportlab==4.4.7; extra == "dev"
Requires-Dist: ruff==0.14.11; extra == "dev"
Requires-Dist: shellcheck-py==0.11.0.1; extra == "dev"
Requires-Dist: shfmt-py==3.12.0.2; extra == "dev"
Requires-Dist: sphinx-lint==1.0.2; extra == "dev"
Requires-Dist: sphinx-toolbox==4.1.1; extra == "dev"
Requires-Dist: sphinxcontrib-confluencebuilder==2.17.1; extra == "dev"
Requires-Dist: sphinxcontrib-spelling==8.0.2; extra == "dev"
Requires-Dist: ty==0.0.10; extra == "dev"
Requires-Dist: types-docutils==0.22.3.20251115; extra == "dev"
Requires-Dist: vulture==2.14; extra == "dev"
Requires-Dist: yamlfix==1.19.1; extra == "dev"
Requires-Dist: zizmor==1.20.0; extra == "dev"
Provides-Extra: release
Requires-Dist: check-wheel-contents==0.6.3; extra == "release"
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 builder only.
   * 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
