stuff: will squash all of this anyway

README.md

@@ -0,0 +1,96 @@
+# xconfluencebuilder
+
+This program is a drop-in replacement for the [Atlassian Confluence Builder for
+Sphinx](https://github.com/sphinx-contrib/confluencebuilder). It
+exports/dumps/archives the build output of the confluencebuilder Sphinx builder
+into a generic interchangeable format, which can be used in conjunction with
+other publishers than the built-in one. The program does not require
+connectivity to a Confluence instance.
+
+The program may be useful in circumstances where a Python3 runtime is not
+available on the machine responsible for publishing to Confluence. 
+
+For more information on why this program exists, please refer to
+[confluencebuilder Issue
+823](https://github.com/sphinx-contrib/confluencebuilder/issues/823).
+
+For a reference implementation of an external publisher, please refer to
+[PSConfluencePublisher](https://bitbucket.org/victorykit/psconfluencepublisher),
+a standalone PowerShell publisher for *Atlassian Confluence Builder for Sphinx*.
+
+## Installing
+
+You can install this extension via PyPI (through pip):
+
+```
+python3 -m pip install victorykit-xconfluencebuilder
+```
+
+or via the sources by cloning the repository (then changing into the directory),
+and also using pip
+
+```
+$ git clone https://bitbucket.org/victorykit/xconfluencebuilder.git
+...
+$ python3 -m pip install .
+```
+
+## Usage
+
+In addition to the basic configuration outlined here, you can find a usage 
+example under `samples/`.
+
+* Register the extension sphinxcontrib.confluencebuilder in the project's 
+  configuration script (conf.py):
+
+```
+extensions = [
+    'xconfluencebuilder'
+]
+```
+
+* Run sphinx-build with the builder confluence:
+
+```
+sphinx-build -b xconfluence . _build/confluence -E -a
+ (or)
+ python -m sphinx -b xconfluence . _build/confluence -E -a
+```
+
+Afterwards, archive the output directory and use it for interchange with an
+external publisher like the aforementioned 
+[PSConfluencePublisher](https://bitbucket.org/victorykit/psconfluencepublisher).
+
+More information on the usage of this extension can be obtained from the
+extension's documentation this is a drop-in for:
+
+> [Atlassian Confluence Builder for Sphinx Tutorial](https://sphinxcontrib-confluencebuilder.readthedocs.io/tutorial)
+
+## Configuration
+
+In addition to the configuration parameters provided by
+`sphinxcontrib.confluencebuilder`, the following parameters are available:
+
+* `xconfluence_outdir` - base directory for archive output (default:
+  `{outdir}/confluence.out`)
+* `xconfluence_manifest_basename` - basename of the asset manifest
+
+The following `confluencebuilder` configuration parameters are not available: 
+
+* `confluence_publish_dry_run` (as if set to `False`)
+
+The `confluence_publish` parameter must still however be set (to `True`), as 
+well as all other configuration parameters which would be required for a minimal
+configuration of `confluencebuilder`. Please refer to [confluencebuilder
+documentation](https://sphinxcontrib-confluencebuilder.readthedocs.io/tutorial) 
+on how to do so.
+
+## Testing
+
+We're patching/mocking a couple of things of the original extension, to make
+this work. Writing proper unit tests for this would take some time to figure out.
+We'll discuss this with the original author of the extension.
+
+## Issue Tracking
+
+Will be provided shortly.

samples/default/Pipfile

@@ -7,7 +7,7 @@ name = 'pypi'
 python_version = '3'
 
 [scripts]
-"sphinx-build" = "sphinx-build docs build --color -W -bx_confluence"
+"sphinx-build" = "sphinx-build docs build --color -W -bxconfluence"
 
 [packages]
 xconfluencebuilder = {editable = true, path = "./../.."}

samples/default/docs/conf.py

@@ -31,6 +31,6 @@ confluence_space_key = '~Tiara.Rodney@adesso.de'
 
 confluence_publish = True
 
-confluence_publish_dryrun = True
+confluence_publish_dryrun = False
 
 confluence_publish_token = 'OTI5NjA5ODc4MzQ5Oh1iD55oEGu7XKRazXHAW5p8mR5r'

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
-name = x-confluencebuilder
-version = 1.0.0-alpha.1
+name = victorykit-xconfluencebuilder
+version = 1.0.0
 author = Theodor Rodweil
 author_email = theodor.rodweil@victory-k.it
 description = sphinxcontrib.confluencebuilder wrapper for delayed publishing
@@ -9,17 +9,16 @@ long_description_content_type = text/markdown
 
 classifiers = 
 ´   topic = : Software Development :: Libraries :: Python Modules
-	Programming Language :: Python :: 3
-	Operating System :: OS Independent
-	License :: Other/Proprietary License
+    Programming Language :: Python :: 3
+    Operating System :: OS Independent
+    License :: Other/Proprietary License
 
 [options]
 install_requires =
-	sphinx >=4.5,<5
-	sphinxcontrib-confluencebuilder
+    sphinxcontrib-confluencebuilder >=2.2.0,<3
 zip_safe = true
 package_dir = 
-	=src
+    =src
 python_requires = >=3.7
 test_suite = test
 packages = find:

src/xconfluencebuilder/__init__.py

@@ -1,14 +1,7 @@
 #!/usr/bin/env python3
 """Publishment delay wrapper sphinxcontrib.confluencebuilder
 
-This is a lightweight pass-through wrapper for 
-``sphinxcontrib.confluencebuilder``, which intercepts all ``store_*`` calls on 
-a ``ConfluencePublisher`` instance, dumps all data into interchange. 
-The index and dumps can be used in conjunction with the PowerShell 
-helper to delay/replay the publishment of pages and attachments for a different 
-Confluence instance, than what the programmatic target is.
-
-The builder name is ``x_confluence``
+The builder name is ``xconfluence``
 
 ``Publisher``, ``Builder``, as well as ``Rest`` instances are mocked and are 
 supressing any HTTP connectivity should the ``confluence_publish_dry_run`` be 
@@ -258,7 +251,7 @@ class ConfluencePublisher(_ConfluencePublisher):
 
         file_name = quote_plus(name)
 
-        output_basepath = Path(getattr(self.config, 'x_confluence_outdir'))
+        output_basepath = Path(getattr(self.config, 'xconfluence_outdir'))
 
         file_ = output_basepath / 'attachments' / file_name
 
@@ -291,7 +284,7 @@ class ConfluencePublisher(_ConfluencePublisher):
         """
         logger.info('pass-through intercept: store_page')
 
-        output_basepath = Path(getattr(self.config, 'x_confluence_outdir'))
+        output_basepath = Path(getattr(self.config, 'xconfluence_outdir'))
 
         file_name = f"{quote_plus(page_name)}.xml"
 
@@ -343,7 +336,7 @@ class ConfluencePublisher(_ConfluencePublisher):
         coupled so that pythonic variable names don't enforce the structure of
         the manifest schema.
         """
-        file_ = (Path(getattr(self.config, 'x_confluence_outdir')) / 
+        file_ = (Path(getattr(self.config, 'xconfluence_outdir')) / 
                  'manifest.json')
 
         file_.parent.mkdir(parents = True, exist_ok=True)
@@ -379,7 +372,7 @@ class ConfluencePublisher(_ConfluencePublisher):
 class ConfluenceBuilder(_ConfluenceBuilder):
     """
     """
-    name = 'x_confluence'
+    name = 'xconfluence'
 
     def __init__(self, app: Sphinx, env = None):
         """
@@ -408,13 +401,13 @@ def setup(app: Sphinx):
     patch_target = 'sphinxcontrib.confluencebuilder.ConfluenceBuilder'
 
     app.add_config_value(
-        name = 'x_confluence_outdir',
+        name = 'xconfluence_outdir',
         default = str(Path(app.outdir) / 'confluence.out'),
         rebuild = True
     )
 
     app.add_config_value(
-        name = 'x_confluence_manifest_basename',
+        name = 'xconfluence_manifest_basename',
         default = 'manifest.json',
         rebuild = True
     )