From 2b1a875a089dfa668f76ca90c7a1f8b5d15b8876 Mon Sep 17 00:00:00 2001 From: "Rodweil, Theodor" Date: Mon, 7 Aug 2023 02:15:15 +0200 Subject: [PATCH] stuff: will squash all of this anyway --- README.md | 96 ++++++++++++++++++++++++++++++ samples/default/Pipfile | 2 +- samples/default/docs/conf.py | 2 +- setup.cfg | 15 +++-- src/xconfluencebuilder/__init__.py | 21 +++---- 5 files changed, 112 insertions(+), 24 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..351280c --- /dev/null +++ b/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. diff --git a/samples/default/Pipfile b/samples/default/Pipfile index 4c48777..7ee4eb7 100644 --- a/samples/default/Pipfile +++ b/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 = "./../.."} diff --git a/samples/default/docs/conf.py b/samples/default/docs/conf.py index 6059fbd..b904a4d 100644 --- a/samples/default/docs/conf.py +++ b/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' diff --git a/setup.cfg b/setup.cfg index 6af33e2..65f44d9 100644 --- a/setup.cfg +++ b/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: diff --git a/src/xconfluencebuilder/__init__.py b/src/xconfluencebuilder/__init__.py index 0ab554a..c503149 100644 --- a/src/xconfluencebuilder/__init__.py +++ b/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 )