sphinx-confluence-relay 0.0.0__tar.gz

sphinx_confluence_relay-0.0.0/LICENSE

@@ -0,0 +1,22 @@
+Copyright 2026 jdknight
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

sphinx_confluence_relay-0.0.0/LICENSE-3RD-PARTY

@@ -0,0 +1,115 @@
+Licenses for incorporated software
+==================================
+
+----------------------------------------------------------------------
+
+Embedded Swagger UI Bundle
+
+----------------------------------------------------------------------
+
+/*!
+	Copyright (c) 2018 Jed Watson.
+	Licensed under the MIT License (MIT), see
+	http://jedwatson.github.io/classnames
+*/
+
+/*!
+ * @description Recursive object extending
+ * @author Viacheslav Lotsmanov <lotsmanov89@gmail.com>
+ * @license MIT
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2013-2018 Viacheslav Lotsmanov
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+/*!
+ * The buffer module from node.js, for the browser.
+ *
+ * @author   Feross Aboukhadijeh <https://feross.org>
+ * @license  MIT
+ */
+
+/*!
+ * https://github.com/Starcounter-Jack/JSON-Patch
+ * (c) 2017-2021 Joachim Wester
+ * MIT license
+ */
+
+/*!
+ * https://github.com/Starcounter-Jack/JSON-Patch
+ * (c) 2017-2022 Joachim Wester
+ * MIT licensed
+ */
+
+/*!
+ * repeat-string <https://github.com/jonschlinkert/repeat-string>
+ *
+ * Copyright (c) 2014-2015, Jon Schlinkert.
+ * Licensed under the MIT License.
+ */
+
+/*! @license DOMPurify 3.4.0 | (c) Cure53 and other contributors | Released under the Apache license 2.0 and Mozilla Public License 2.0 | github.com/cure53/DOMPurify/blob/3.4.0/LICENSE */
+
+/*! ieee754. BSD-3-Clause License. Feross Aboukhadijeh <https://feross.org/opensource> */
+
+/*! js-yaml 4.1.1 https://github.com/nodeca/js-yaml @license MIT */
+
+/*! safe-buffer. MIT License. Feross Aboukhadijeh <https://feross.org/opensource> */
+
+/**
+ * @license React
+ * react-dom.production.min.js
+ *
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * @license React
+ * react.production.min.js
+ *
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * @license React
+ * scheduler.production.min.js
+ *
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * @license React
+ * use-sync-external-store-with-selector.production.js
+ *
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */

sphinx_confluence_relay-0.0.0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: sphinx-confluence-relay
+Version: 0.0.0
+Summary: Publish service for Confluence Sphinx Documentation Manifests
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Documentation :: Sphinx
+License-File: LICENSE
+License-File: LICENSE-3RD-PARTY
+Requires-Dist: apscheduler
+Requires-Dist: fastapi[standard]
+Requires-Dist: sqlmodel
+Project-URL: Download, https://pypi.python.org/pypi/sphinx-confluence-relay
+Project-URL: Source, https://github.com/jdknight/sphinx-confluence-relay
+
+# Sphinx Confluence Relay
+
+[![pip Version](https://badgen.net/pypi/v/sphinx-confluence-relay?label=PyPI)](https://pypi.python.org/pypi/sphinx-confluence-relay)
+[![Build Status](https://github.com/jdknight/sphinx-confluence-relay/actions/workflows/build.yml/badge.svg)](https://github.com/jdknight/sphinx-confluence-relay/actions/workflows/build.yml)
+
+## Overview
+
+The project provides the ability to create a "relay" service that accepts
+generated manifest files from
+[Atlassian Confluence Builder for Sphinx][confluencebuilder] and publish
+them to a pre-configured Confluence Data Center instance (Confluence Cloud
+is not supported). Using such a service allows system administrators to setup
+publish relaying where users do not need to expose their Confluence tokens.
+
+## Requirements
+
+* [Python][python] 3.11+
+* [APScheduler][apscheduler]
+* [FastAPI][fastapi]
+* [SQLModel][sqlmodel]
+
+# Usage
+
+Users of a running service will publish using at least three key components:
+
+- A [data-embedded manifest][confluence-manifest-data] generated from
+  Atlassian Confluence Builder for Sphinx.
+- The key of a space to publish into.
+- The parent page name/identifier to publish documentation under.
+
+A publish event will take a manifest and upload all pages/attachments into
+a given target space. After pages/attachments are uploaded, any legacy content
+hosted on Confluence will be removed. Publication and removals are contained
+to the descendants of the configured parent page. Requests that would require
+moving pages in a space into the parent page's descendants will be ignored.
+
+Publish events are queued. The service can accept multiple requests and will
+process them in a first-in-first-out (FIFO) order. Pages/attachments are only
+uploaded if required (i.e. changed).
+
+Users may use the REST interface of a hosted service utilizing any common
+tools (e.g. [curl][curl]). Alternatively, if this package is installed on a
+client system, users may utilize the publish helper tool:
+
+```none
+sphinx-confluence-relay-publish --help
+ (or)
+python -m sphinx_confluence_relay --help
+```
+
+For example:
+
+```none
+sphinx-confluence-relay-publish http://upload.wiki.example.com/ --space-key MYSPACE --parent-page Documentation
+```
+
+If a manifest file is not provided via the `--manifest` argument, the default
+paths searched for will be:
+
+```none
+scb-manifest.json
+ (or)
+_build/confluence/scb-manifest.json
+ (or)
+_build/singleconfluence/scb-manifest.json
+```
+
+If a system administrator has configured authentication requirements, a token
+can be passed a couple of ways. The utility accepts a token value from the
+environment:
+
+```
+SPHINX_CONFLUENCE_RELAY_PUBLISH_TOKEN
+```
+
+Passed in using the standard input stream with `--password-stdin`:
+
+```none
+cat ~/.token | sphinx-confluence-relay-publish ... --password-stdin
+```
+
+Or passed in using the `--token` argument:
+
+```none
+sphinx-confluence-relay-publish ... --token <TOKEN>
+```
+
+# Service Installation
+
+## Configuration
+
+The relay service relies on a TOML configuration file. A template of this
+configuration can be found in the root of this repository:
+
+```none
+sphinx-confluence-relay.toml.default
+```
+
+A system administrator will typically prepare a `sphinx-confluence-relay.toml`
+file on a host. sphinx-confluence-relay will search for configurations found
+in the following paths:
+
+```none
+sphinx-confluence-relay.toml
+ (or)
+/etc/sphinx-confluence-relay.toml  (non-Windows)
+```
+
+A bare minimum configuration required is the configuration of the Confluence
+Data Center API URL and the token that will be used for REST interaction:
+
+```toml
+[sphinx-confluence-relay]
+confluence-url = 'https://wiki.example.com/rest/api/'
+confluence-token = ''
+```
+
+If a system administrator wishes to require tokens for publish requests,
+they can register one or more tokens in a `publish-tokens` option:
+
+```toml
+publish-tokens = [
+    'SOME_TOKEN',
+]
+```
+
+By default, all spaces the Confluence token can access could be published to.
+If an environment is looking to restrict only publishing to specific pages,
+individual spaces can be populated in a `spaces` option:
+
+```toml
+spaces = [
+    'MYSPACE',
+]
+```
+
+For additional advanced options, refer to the template configuration.
+
+## Manual Service Setup
+
+System administrators may manually setup using the following instructions.
+Adjusts paths to desired preferences.
+
+Build a path to hold packages:
+
+```none
+mkdir /opt/sphinx-confluence-relay
+cd /opt/sphinx-confluence-relay
+```
+
+Create a virtual environment:
+
+```none
+python -m venv .venv
+source .venv/bin/activate
+```
+
+Install this service using [pip][pip]:
+
+```none
+pip install sphinx-confluence-relay
+```
+
+Place the prepare configuration file in the local directory with the name:
+
+```none
+sphinx-confluence-relay.toml
+```
+
+Run this service:
+
+```none
+uvicorn sphinx_confluence_relay.main:app --host 0.0.0.0 --port 8080
+```
+
+## Docker
+
+This project supports multiple ways to use this utility inside a Docker
+environment. A recommended choice is to use a pre-built image available
+from GitHub's container registry.
+
+### Pre-built image
+
+A pre-built image can be acquired using the following command:
+
+```none
+docker pull ghcr.io/jdknight/sphinx-confluence-relay
+```
+
+On the host what will run Docker, copy the configuration file into this path:
+
+```none
+/etc/sphinx-confluence-relay.toml
+```
+
+Ensure the path is available for holding a database of queued requests and
+status information:
+
+```none
+/var/lib/sphinx-confluence-relay/
+```
+
+The container than can be run using the following command:
+
+```none
+docker run --name sphinx-confluence-relay --detach --restart unless-stopped \
+    -p 8080:8080 \
+    -v /etc/sphinx-confluence-relay.toml:/etc/sphinx-confluence-relay.toml:ro \
+    -v /var/lib/sphinx-confluence-relay/:/database.db \
+    ghcr.io/jdknight/sphinx-confluence-relay
+```
+
+### Self-built image
+
+Users who wish to manage their own image can do so with the Docker
+definitions found inside this repository. This can be done by cloning
+this repository on the host wanting to run the container. A Docker
+build can be run using:
+
+```none
+docker build -t ghcr.io/jdknight/sphinx-confluence-relay \
+    --detach -f docker/Dockerfile .
+```
+
+Then running the same `docker run` call mentioned above.
+
+### Self-managed Docker Compose
+
+Users can also take advantage of the Docker compose definition. For a
+working directory to hold Docker Compose content, ensure a settings file
+is setup:
+
+```none
+sphinx-confluence-relay.toml
+```
+
+Next, load up the container using `docker compose`:
+
+```none
+docker compose build
+docker compose up --detach
+```
+
+Both Docker build calls will by default load a container with the
+PyPI version of sphinx-confluence-relay. Users wanting to use the local
+implementation in their container can do so by performing a Docker build
+with the `--build-arg local` argument.
+
+For example:
+
+```none
+docker compose build --build-arg BUILD_MODE=local
+docker compose up --detach
+```
+
+
+[apscheduler]: https://apscheduler.readthedocs.io/
+[confluence-manifest-data]: https://sphinxcontrib-confluencebuilder.readthedocs.io/configuration/#confval-confluence_manifest_data
+[confluencebuilder]: https://sphinxcontrib-confluencebuilder.readthedocs.io/
+[curl]: https://curl.se/
+[fastapi]: https://fastapi.tiangolo.com/
+[pip]: https://pip.pypa.io/
+[python]: https://www.python.org/
+[sqlmodel]: https://sqlmodel.tiangolo.com/
+

sphinx_confluence_relay-0.0.0/README.md

@@ -0,0 +1,264 @@
+# Sphinx Confluence Relay
+
+[![pip Version](https://badgen.net/pypi/v/sphinx-confluence-relay?label=PyPI)](https://pypi.python.org/pypi/sphinx-confluence-relay)
+[![Build Status](https://github.com/jdknight/sphinx-confluence-relay/actions/workflows/build.yml/badge.svg)](https://github.com/jdknight/sphinx-confluence-relay/actions/workflows/build.yml)
+
+## Overview
+
+The project provides the ability to create a "relay" service that accepts
+generated manifest files from
+[Atlassian Confluence Builder for Sphinx][confluencebuilder] and publish
+them to a pre-configured Confluence Data Center instance (Confluence Cloud
+is not supported). Using such a service allows system administrators to setup
+publish relaying where users do not need to expose their Confluence tokens.
+
+## Requirements
+
+* [Python][python] 3.11+
+* [APScheduler][apscheduler]
+* [FastAPI][fastapi]
+* [SQLModel][sqlmodel]
+
+# Usage
+
+Users of a running service will publish using at least three key components:
+
+- A [data-embedded manifest][confluence-manifest-data] generated from
+  Atlassian Confluence Builder for Sphinx.
+- The key of a space to publish into.
+- The parent page name/identifier to publish documentation under.
+
+A publish event will take a manifest and upload all pages/attachments into
+a given target space. After pages/attachments are uploaded, any legacy content
+hosted on Confluence will be removed. Publication and removals are contained
+to the descendants of the configured parent page. Requests that would require
+moving pages in a space into the parent page's descendants will be ignored.
+
+Publish events are queued. The service can accept multiple requests and will
+process them in a first-in-first-out (FIFO) order. Pages/attachments are only
+uploaded if required (i.e. changed).
+
+Users may use the REST interface of a hosted service utilizing any common
+tools (e.g. [curl][curl]). Alternatively, if this package is installed on a
+client system, users may utilize the publish helper tool:
+
+```none
+sphinx-confluence-relay-publish --help
+ (or)
+python -m sphinx_confluence_relay --help
+```
+
+For example:
+
+```none
+sphinx-confluence-relay-publish http://upload.wiki.example.com/ --space-key MYSPACE --parent-page Documentation
+```
+
+If a manifest file is not provided via the `--manifest` argument, the default
+paths searched for will be:
+
+```none
+scb-manifest.json
+ (or)
+_build/confluence/scb-manifest.json
+ (or)
+_build/singleconfluence/scb-manifest.json
+```
+
+If a system administrator has configured authentication requirements, a token
+can be passed a couple of ways. The utility accepts a token value from the
+environment:
+
+```
+SPHINX_CONFLUENCE_RELAY_PUBLISH_TOKEN
+```
+
+Passed in using the standard input stream with `--password-stdin`:
+
+```none
+cat ~/.token | sphinx-confluence-relay-publish ... --password-stdin
+```
+
+Or passed in using the `--token` argument:
+
+```none
+sphinx-confluence-relay-publish ... --token <TOKEN>
+```
+
+# Service Installation
+
+## Configuration
+
+The relay service relies on a TOML configuration file. A template of this
+configuration can be found in the root of this repository:
+
+```none
+sphinx-confluence-relay.toml.default
+```
+
+A system administrator will typically prepare a `sphinx-confluence-relay.toml`
+file on a host. sphinx-confluence-relay will search for configurations found
+in the following paths:
+
+```none
+sphinx-confluence-relay.toml
+ (or)
+/etc/sphinx-confluence-relay.toml  (non-Windows)
+```
+
+A bare minimum configuration required is the configuration of the Confluence
+Data Center API URL and the token that will be used for REST interaction:
+
+```toml
+[sphinx-confluence-relay]
+confluence-url = 'https://wiki.example.com/rest/api/'
+confluence-token = ''
+```
+
+If a system administrator wishes to require tokens for publish requests,
+they can register one or more tokens in a `publish-tokens` option:
+
+```toml
+publish-tokens = [
+    'SOME_TOKEN',
+]
+```
+
+By default, all spaces the Confluence token can access could be published to.
+If an environment is looking to restrict only publishing to specific pages,
+individual spaces can be populated in a `spaces` option:
+
+```toml
+spaces = [
+    'MYSPACE',
+]
+```
+
+For additional advanced options, refer to the template configuration.
+
+## Manual Service Setup
+
+System administrators may manually setup using the following instructions.
+Adjusts paths to desired preferences.
+
+Build a path to hold packages:
+
+```none
+mkdir /opt/sphinx-confluence-relay
+cd /opt/sphinx-confluence-relay
+```
+
+Create a virtual environment:
+
+```none
+python -m venv .venv
+source .venv/bin/activate
+```
+
+Install this service using [pip][pip]:
+
+```none
+pip install sphinx-confluence-relay
+```
+
+Place the prepare configuration file in the local directory with the name:
+
+```none
+sphinx-confluence-relay.toml
+```
+
+Run this service:
+
+```none
+uvicorn sphinx_confluence_relay.main:app --host 0.0.0.0 --port 8080
+```
+
+## Docker
+
+This project supports multiple ways to use this utility inside a Docker
+environment. A recommended choice is to use a pre-built image available
+from GitHub's container registry.
+
+### Pre-built image
+
+A pre-built image can be acquired using the following command:
+
+```none
+docker pull ghcr.io/jdknight/sphinx-confluence-relay
+```
+
+On the host what will run Docker, copy the configuration file into this path:
+
+```none
+/etc/sphinx-confluence-relay.toml
+```
+
+Ensure the path is available for holding a database of queued requests and
+status information:
+
+```none
+/var/lib/sphinx-confluence-relay/
+```
+
+The container than can be run using the following command:
+
+```none
+docker run --name sphinx-confluence-relay --detach --restart unless-stopped \
+    -p 8080:8080 \
+    -v /etc/sphinx-confluence-relay.toml:/etc/sphinx-confluence-relay.toml:ro \
+    -v /var/lib/sphinx-confluence-relay/:/database.db \
+    ghcr.io/jdknight/sphinx-confluence-relay
+```
+
+### Self-built image
+
+Users who wish to manage their own image can do so with the Docker
+definitions found inside this repository. This can be done by cloning
+this repository on the host wanting to run the container. A Docker
+build can be run using:
+
+```none
+docker build -t ghcr.io/jdknight/sphinx-confluence-relay \
+    --detach -f docker/Dockerfile .
+```
+
+Then running the same `docker run` call mentioned above.
+
+### Self-managed Docker Compose
+
+Users can also take advantage of the Docker compose definition. For a
+working directory to hold Docker Compose content, ensure a settings file
+is setup:
+
+```none
+sphinx-confluence-relay.toml
+```
+
+Next, load up the container using `docker compose`:
+
+```none
+docker compose build
+docker compose up --detach
+```
+
+Both Docker build calls will by default load a container with the
+PyPI version of sphinx-confluence-relay. Users wanting to use the local
+implementation in their container can do so by performing a Docker build
+with the `--build-arg local` argument.
+
+For example:
+
+```none
+docker compose build --build-arg BUILD_MODE=local
+docker compose up --detach
+```
+
+
+[apscheduler]: https://apscheduler.readthedocs.io/
+[confluence-manifest-data]: https://sphinxcontrib-confluencebuilder.readthedocs.io/configuration/#confval-confluence_manifest_data
+[confluencebuilder]: https://sphinxcontrib-confluencebuilder.readthedocs.io/
+[curl]: https://curl.se/
+[fastapi]: https://fastapi.tiangolo.com/
+[pip]: https://pip.pypa.io/
+[python]: https://www.python.org/
+[sqlmodel]: https://sqlmodel.tiangolo.com/