CHANGELOG.md

@@ -10,38 +10,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 nothing as of yet
 
-## [1.1.2] - 2023-08-07
-
-### Added
-
-- link to changelog in package metadata
-
-### Changed
-
-- manifest example in README as to reflect the latest default sample output
-
-### Fixed
-
-- deprecated `license_file` property in package metadata 
-
-## [1.1.1] - 2023-08-07
-
-### Added
-
-- basic test which makes sure the default sample executes without errors
-
-### Changed
-
-- metadata of python package as to make it more user-friendly when browsing PyPI
-
-### Fixed
-
-- licensing issue with default sample, as it was previously unlicensed
-
-### Removed
-
-- redundant default sample configuration
-
 
 ## [1.1.0] - 2023-08-07
 
@@ -71,8 +39,6 @@ nothing as of yet
 
 
 [unreleased]: https://bitbucket.org/victorykit/xconfluencebuilder/branch/master
-[1.1.2]: https://bitbucket.org/victorykit/xconfluencebuilder/src/v1.1.2/
-[1.1.1]: https://bitbucket.org/victorykit/xconfluencebuilder/src/v1.1.1/
 [1.1.0]: https://bitbucket.org/victorykit/xconfluencebuilder/src/v1.1.0/
 [1.0.1]: https://bitbucket.org/victorykit/xconfluencebuilder/src/v1.0.1/
 [1.0.0]: https://bitbucket.org/victorykit/xconfluencebuilder/src/v1.0.0/

README.md

@@ -38,19 +38,19 @@ The following is a sample manifest generated from the default sample:
             "Name": "pexels-just-a-couple-photos-3777622.jpg",
             "ContainerPageTitle": "Cats",
             "MimeType": "image/jpeg",
-            "Ref": "attachments/Cats/pexels-just-a-couple-photos-3777622.jpg"
+            "Ref": "attachments/pexels-just-a-couple-photos-3777622.jpg"
         },
         {
             "Name": "pexels-sami-aksu-14356302.jpg",
             "ContainerPageTitle": "Cats",
             "MimeType": "image/jpeg",
-            "Ref": "attachments/Cats/pexels-sami-aksu-14356302.jpg"
+            "Ref": "attachments/pexels-sami-aksu-14356302.jpg"
         },
         {
             "Name": "objects.inv",
             "ContainerPageTitle": "Default Sample~",
             "MimeType": "application/octet-stream",
-            "Ref": "attachments/Default+Sample~/objects.inv"
+            "Ref": "attachments/objects.inv"
         }
     ]
 }

samples/default/docs/conf.py

@@ -3,9 +3,12 @@
 """
 __author__ = 'theodor.rodweil@victory-k.it'
 __copyright__ = '2023 - Victory Karma IT'
-__license__ = 'DL-DE-BY-2.0'
+__license__ = 'UNLICENSED'
 __version__ = "1.0"
 
+import sys
+from pathlib import Path
+
 # -- Project information -------------------------------------------------------
 
 project = 'Default Sample'
@@ -22,9 +25,9 @@ extensions = ['xconfluencebuilder']
 
 exclude_patterns = ['Pipfile*', 'build', '.DS_Store', '.venv']
 
-confluence_server_url = 'https://confluence.example.com/'
+confluence_server_url = 'https://confluence.adesso.de/'
 
-confluence_space_key = 'SampleSpace'
+confluence_space_key = '~Tiara.Rodney@adesso.de'
 
 confluence_publish = True
 

samples/default/docs/confluence_conf.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""Wrapper for Confluence Sphinx Builder
+
+enables support for configuration through shell environment variables
+
+.. warning::
+    make sure to pin a concrete version of the ````
+"""
+__author__ = 'theodor.rodweil@victory-k.it'
+__copyright__ = '2023 - Victory Karma IT'
+__license__ = 'DL-DE-BY-2.0'
+__version__ = '1.2.0'
+
+
+from dataclasses import dataclass, fields, asdict
+from typing import Any, Optional, Callable, Type
+from os import environ
+
+
+#: rudimentary typecasting of serialized Python built-ins
+DEFAULT_TYPECASTS = {
+    'str': lambda inp: str(inp),
+    'bool': lambda inp: {'true': True, 'false': False}[inp.lower()]
+}
+
+
+def get_config_from_environ(
+    typecasts: dict[str, Callable] = DEFAULT_TYPECASTS
+) -> 'ConfluenceBuilderConfig':
+    """get confluence builder config from environment
+
+    :param typecasts: a collection of built-in typecast functions
+    """
+    props = {field.name:field.type for field in fields(ConfluenceBuilderConfig)}
+
+    prop_names = props.keys()
+
+    out = {}
+
+    for environ_name in dict(environ).keys():
+
+        env_name = environ_name
+
+        if env_name in prop_names:
+
+            type_name = props[env_name].__name__
+
+            if type_name == 'Optional':
+
+                type_name = props[env_name].__args__[0].__name__
+
+            value = typecasts[type_name](
+                environ[environ_name]
+            )
+
+            if value is not None:
+
+                out[env_name] = value
+
+    try:
+
+        return ConfluenceBuilderConfig(**out)
+
+    except TypeError as err:
+
+        raise TypeError(f'error getting config from environ: {err}') from err
+
+
+def apply_config(
+    config: 'ConfluenceBuildConfig',
+    env: dict = globals()
+) -> None:
+    """apply confluence builder config to runtime environment
+
+    :param config: configuration instance object
+    :param env: global runtime variables instance object
+    """
+    for key, value in asdict(config).items():
+
+        env[key.lower()] = value
+
+
+@dataclass
+class ConfluenceBuilderConfig:
+    """partial configuration of the Confluence builder for Sphinx
+
+    see 
+    `https://sphinxcontrib-confluencebuilder.readthedocs.io/en/stable/configuration/`_
+    , for more information.
+
+    """
+    #: The URL for the Confluence instance to publish to.
+    CONFLUENCE_SERVER_URL: str
+
+    #: The username value used to authenticate with the Confluence instance.
+    CONFLUENCE_SERVER_USER: Optional[str] = None
+
+    #: Key of the space in Confluence to be used to publish generated documents
+    CONFLUENCE_SPACE_KEY: Optional[str] = None
+
+    #: The username value used to authenticate with the Confluence instance.
+    CONFLUENCE_PUBLISH_DRYRUN: Optional[bool] = None
+
+    #: A boolean that decides whether or not to allow publishing.
+    CONFLUENCE_PUBLISH: bool = True
+
+    #: A boolean value to whether or not nest pages in a hierarchical ordered.
+    CONFLUENCE_PAGE_HIERARCHY: bool = True
+
+    #: The password value used to authenticate with the Confluence instance.
+    CONFLUENCE_SERVER_PASS: Optional[str] = None
+
+    #: The personal access token value used to authenticate with the Confluence 
+    #  instance
+    CONFLUENCE_PUBLISH_TOKEN: Optional[str] = None
+
+    #: The root page found inside the configured space (confluence_space_key) 
+    #  where published pages will be a descendant of
+    CONFLUENCE_PARENT_PAGE: Optional[str] = None
+
+    @staticmethod
+    def from_environ() -> 'ConfluenceBuilderConfig':
+        """get a new configuration object
+        """
+
+        return get_config_from_environ()
+
+    def apply(self: Type, env: dict = globals()) -> None:
+        """apply the configuration to the current runtime environment
+        """
+
+        return apply_config(self, env)

setup.cfg

@@ -6,11 +6,6 @@ author_email = theodor.rodweil@victory-k.it
 description = sphinxcontrib.confluencebuilder wrapper for delayed publishing
 long_description = file: README.md
 long_description_content_type = text/markdown
-license = DL-DE-BY-2.0
-license_files = LICENSE
-project_urls =
-    Changelog = https://bitbucket.org/victorykit/xconfluencebuilder/src/master/CHANGELOG.md
-    Repository = https://bitbucket.org/victorykit/xconfluencebuilder/
 
 classifiers = 
 ´   topic = : Software Development :: Libraries :: Python Modules

tox.ini

@@ -3,15 +3,6 @@ skipsdist = true
 maxversion = 3.7.0
 isolated_build = True
 
-[testenv:test-sample-default]
-description = test the default sample
-basepython = python3
-changedir = samples/default
-setenv =
-    PIPENV_IGNORE_VIRTUALENVS = 1
-deps = pipenv
-commands =
-    python3 -m pipenv run sphinx-build
 
 [testenv:lint]
 description = lint with pylint