feat: init

samples/default/docs/cats.rst

@@ -0,0 +1,13 @@
+####
+Cats
+####
+
+What can we say... They secretly rule the world.
+
+.. image:: _media/pexels-just-a-couple-photos-3777622.jpg
+
+photo by: https://www.pexels.com/@jacp/
+
+.. image:: _media/pexels-sami-aksu-14356302.jpg
+
+photo by: https://www.pexels.com/@sami-aksu-48867324/

samples/default/docs/conf.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""
+"""
+__author__ = 'theodor.rodweil@victory-k.it'
+__copyright__ = '2023 - Victory Karma IT'
+__license__ = 'UNLICENSED'
+__version__ = "1.0"
+
+import sys
+from pathlib import Path
+
+# -- Project information -------------------------------------------------------
+
+project = 'Default Sample'
+
+copyright = __copyright__
+
+author = __author__
+
+# `release` is supported, yet some extensions still use the deprecated `version`
+release = __version__
+version = release
+
+extensions = ['xconfluencebuilder']
+
+exclude_patterns = ['Pipfile*', 'build', '.DS_Store', '.venv']
+
+confluence_server_url = 'https://confluence.adesso.de/'
+
+confluence_space_key = '~Tiara.Rodney@adesso.de'
+
+confluence_publish = True
+
+confluence_publish_dryrun = True
+
+confluence_publish_token = 'OTI5NjA5ODc4MzQ5Oh1iD55oEGu7XKRazXHAW5p8mR5r'

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)

samples/default/docs/index.rst

@@ -0,0 +1,38 @@
+###############
+Default Sample~
+###############
+
+.. note::
+
+    ``confluence_conf.py`` is not required, it's just a helper module to be 
+    able to configure ``sphinxcontrib.confluencebuilder`` through environment 
+    variables.
+
+To run this sample, `pipenv <https://pypi.org/project/pipenv/>`_ is required.
+
+First, install the *venv* by executing the following command from within the
+``samples/default/`` directory:
+
+.. code-block::
+
+    $ python3 -m pipenv install
+
+.. note::
+
+    To contain the virtual environment within the current directory, create an
+    empty directory named ``.venv``.
+
+Afterwards, execute the following command:
+
+.. code-block::
+
+    $ python3 -m pipenv run build-sphinx
+
+The backend for the command can be inspected in ``Pipfile``.
+
+You should now have a directory
+
+.. toctree::
+    :caption: Important Content
+    
+    cats