Metadata-Version: 2.1
Name: sphinxcontrib-confluencebuilder
Version: 1.9.0
Summary: Sphinx extension to build Atlassian Confluence Storage Markup
Author-email: Anthony Shaw <anthonyshaw@apache.org>
Maintainer-email: James Knight <james.d.knight@live.com>
License: BSD-2-Clause
Project-URL: Documentation, https://sphinxcontrib-confluencebuilder.readthedocs.io
Project-URL: Download, https://pypi.python.org/pypi/sphinxcontrib-confluencebuilder
Project-URL: Source, https://github.com/sphinx-contrib/confluencebuilder
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Documentation
Classifier: Topic :: Utilities
Requires-Python: >=2.7
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: AUTHORS

.. -*- restructuredtext -*-

=======================================
Atlassian Confluence Builder for Sphinx
=======================================

.. image:: https://img.shields.io/pypi/v/sphinxcontrib-confluencebuilder.svg
   :target: https://pypi.python.org/pypi/sphinxcontrib-confluencebuilder
   :alt: pip Version

.. image:: https://github.com/sphinx-contrib/confluencebuilder/actions/workflows/build.yml/badge.svg
    :target: https://github.com/sphinx-contrib/confluencebuilder/actions/workflows/build.yml
    :alt: Build Status

.. image:: https://readthedocs.org/projects/sphinxcontrib-confluencebuilder/badge/?version=latest
   :target: https://sphinxcontrib-confluencebuilder.readthedocs.io/
   :alt: Documentation Status

.. image:: https://img.shields.io/pypi/dm/sphinxcontrib-confluencebuilder.svg
   :target: https://pypi.python.org/pypi/sphinxcontrib-confluencebuilder/
   :alt: PyPI download month

Sphinx_ extension to build Confluence® compatible markup format files and
optionally publish them to a Confluence instance.

Requirements
============

* Python_ 2.7 or 3.7+
* Requests_ 2.14.0+
* Sphinx_ 1.8 or 4.1+

If publishing:

* Confluence_ Cloud or Data Center / Server 7.8+

Installing
==========

The recommended method to installing this extension is using pip_:

.. code-block:: shell

   pip install sphinxcontrib-confluencebuilder
    (or)
   python -m pip install sphinxcontrib-confluencebuilder

For a more in-depth installation information, see also:

 | Atlassian Confluence Builder for Sphinx - Installation
 | https://sphinxcontrib-confluencebuilder.readthedocs.io/install

Usage
=====

- Register the extension ``sphinxcontrib.confluencebuilder`` in the project's
  configuration script (``conf.py``):

.. code-block:: python

   extensions = [
       'sphinxcontrib.confluencebuilder',
   ]

- Run sphinx-build with the builder ``confluence``:

.. code-block:: shell

   sphinx-build -b confluence . _build/confluence -E -a
    (or)
   python -m sphinx -b confluence . _build/confluence -E -a

For more information on the usage of this extension, see also:

 | Atlassian Confluence Builder for Sphinx - Tutorial
 | https://sphinxcontrib-confluencebuilder.readthedocs.io/tutorial

Configuration
=============

The following is an example of a simple configuration for Confluence generation
and publishing:

.. code-block:: python

   extensions = [
       'sphinxcontrib.confluencebuilder',
   ]
   confluence_publish = True
   confluence_space_name = 'TEST'
   confluence_parent_page = 'Documentation'
   confluence_server_url = 'https://intranet-wiki.example.com/'
   confluence_ask_user = True
   confluence_ask_password = True

For a complete list of configuration options, see also:

 | Atlassian Confluence Builder for Sphinx - Configuration
 | https://sphinxcontrib-confluencebuilder.readthedocs.io/configuration

Features
========

For a complete list of supported markup, extensions, etc.; see:

 | Atlassian Confluence Builder for Sphinx - Features
 | https://sphinxcontrib-confluencebuilder.readthedocs.io/features

For a complete list of directives supported by this extension, see:

 | Atlassian Confluence Builder for Sphinx - Directives
 | https://sphinxcontrib-confluencebuilder.readthedocs.io/directives

Demonstration
=============

A demonstration of this extension can be seen by inspecting the published
validation/testing documents found here:

 | Atlassian Confluence Builder for Sphinx - Online Demo on Confluence Cloud
 | https://sphinxcontrib-confluencebuilder.atlassian.net/

----

| Atlassian Confluence Builder for Sphinx project is unaffiliated with
  Atlassian.
| Atlassian is a registered trademark of Atlassian Pty Ltd.
| Confluence is a registered trademark of Atlassian Pty Ltd.

.. _Confluence: https://www.atlassian.com/software/confluence
.. _Python: https://www.python.org/
.. _Requests: https://pypi.python.org/pypi/requests
.. _Sphinx: https://www.sphinx-doc.org/
.. _pip: https://pip.pypa.io/
