docs: various

.secrets.baseline

@@ -137,7 +137,7 @@
         "filename": "src/starbridge/hello/service.py",
         "hashed_secret": "b96ff7d04dbdf5211aa6bf8ac3a557f30dc7469b",
         "is_verified": false,
-        "line_number": 114,
+        "line_number": 115,
         "is_secret": false
       }
     ],
@@ -152,5 +152,5 @@
       }
     ]
   },
-  "generated_at": "2024-12-31T09:07:15Z"
+  "generated_at": "2025-01-04T15:27:01Z"
 }

README.md

@@ -94,11 +94,15 @@ Starbridge implements the [MCP Server](https://modelcontextprotocol.io/docs/conc
 
 [TODO: Document CLI commands]
 
-## Contributing
 
-Please read our [Contributing Guidelines](https://starbridge.readthedocs.io/en/latest/contributing.html) for how to setup for development, and before making a pull request.
+## Further Reading
 
-## Resources
+* The [Docker manual](https://starbridge.readthedocs.io/en/latest/docker.html) explains how to run Starbridge within Docker.
+* Check out the [reference](https://starbridge.readthedocs.io/en/latest/reference.html) with detailed documentation of public classes and functions.
+* Our [release notes](https://starbridge.readthedocs.io/en/latest/release-notes.html) provide a complete log of recent improvements and changes.
+* In case you want to help us improve Starbridge: The [contribution guidelines](https://starbridge.readthedocs.io/en/latest/contributing.html) explain how to setup your development environment and create pull requests.
+
+## Additional Resources
 
 * [MCP Press release](https://www.anthropic.com/news/model-context-protocol)
 * [MCP Specification and SDKs](https://github.com/modelcontextprotocol)

_readme_footer.md

@@ -0,0 +1,23 @@
+
+## Further Reading
+
+* The [Docker manual](https://starbridge.readthedocs.io/en/latest/docker.html) explains how to run Starbridge within Docker.
+* Check out the [reference](https://starbridge.readthedocs.io/en/latest/reference.html) with detailed documentation of public classes and functions.
+* Our [release notes](https://starbridge.readthedocs.io/en/latest/release-notes.html) provide a complete log of recent improvements and changes.
+* In case you want to help us improve Starbridge: The [contribution guidelines](https://starbridge.readthedocs.io/en/latest/contributing.html) explain how to setup your development environment and create pull requests.
+
+## Additional Resources
+
+* [MCP Press release](https://www.anthropic.com/news/model-context-protocol)
+* [MCP Specification and SDKs](https://github.com/modelcontextprotocol)
+* [MCP Info to amend Claude's context](https://modelcontextprotocol.io/llms-full.txt)
+
+## Star History
+
+<a href="https://star-history.com/#helmut-hoffer-von-ankershoffen/starbridge&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=helmut-hoffer-von-ankershoffen/starbridge&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=helmut-hoffer-von-ankershoffen/starbridge&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=helmut-hoffer-von-ankershoffen/starbridge&type=Date" />
+ </picture>
+</a>

_readme_header.md

@@ -0,0 +1,24 @@
+# [PRE-ALPHA] ⭐ starbridge MCP server for Claude Desktop
+
+[![License](https://img.shields.io/github/license/helmut-hoffer-von-ankershoffen/starbridge?logo=opensourceinitiative&logoColor=3DA639&labelColor=414042&color=A41831)
+](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/blob/main/LICENSE)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/starbridge.svg?logo=python&color=204361&labelColor=1E2933)](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/blob/main/noxfile.py)
+[![CI](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/actions/workflows/test-and-report.yml/badge.svg)](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/actions/workflows/test-and-report.yml)
+[![Read the Docs](https://img.shields.io/readthedocs/starbridge)](https://starbridge.readthedocs.io/)
+[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_starbridge&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_starbridge)
+[![Security](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_starbridge&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_starbridge)
+[![Maintainability](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_starbridge&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_starbridge)
+[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_starbridge&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_starbridge)
+[![Coverage](https://codecov.io/gh/helmut-hoffer-von-ankershoffen/starbridge/graph/badge.svg?token=SX34YRP30E)](https://codecov.io/gh/helmut-hoffer-von-ankershoffen/starbridge)
+[![Ruff](https://img.shields.io/badge/style-Ruff-blue?color=D6FF65)](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/blob/main/noxfile.py)
+[![GitHub - Version](https://img.shields.io/github/v/release/helmut-hoffer-von-ankershoffen/starbridge?label=GitHub&style=flat&labelColor=1C2C2E&color=blue&logo=GitHub&logoColor=white)](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/releases)
+![GitHub - Commits](https://img.shields.io/github/commit-activity/m/helmut-hoffer-von-ankershoffen/starbridge/main?label=commits&style=flat&labelColor=1C2C2E&color=blue&logo=GitHub&logoColor=white)
+[![PyPI - Version](https://img.shields.io/pypi/v/starbridge.svg?label=PyPI&logo=pypi&logoColor=%23FFD243&labelColor=%230073B7&color=FDFDFD)](https://pypi.python.org/pypi/starbridge)
+[![PyPI - Status](https://img.shields.io/pypi/status/starbridge?logo=pypi&logoColor=%23FFD243&labelColor=%230073B7&color=FDFDFD)](https://pypi.python.org/pypi/starbridge)
+[![Docker - Version](https://img.shields.io/docker/v/helmuthva/starbridge?sort=semver&label=Docker&logo=docker&logoColor=white&labelColor=1354D4&color=10151B)](https://hub.docker.com/r/helmuthva/starbridge/tags)
+[![Docker - Size](https://img.shields.io/docker/image-size/helmuthva/starbridge?sort=semver&arch=arm64&label=image&logo=docker&logoColor=white&labelColor=1354D4&color=10151B)](https://hub.docker.com/r/helmuthva/starbridge/)
+<!---
+[![ghcr.io - Version](https://ghcr-badge.egpl.dev/helmut-hoffer-von-ankershoffen/starbridge/tags?color=%2344cc11&ignore=0.0%2C0%2Clatest&n=3&label=ghcr.io&trim=)](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/pkgs/container/starbridge)
+[![ghcr.io - Sze](https://ghcr-badge.egpl.dev/helmut-hoffer-von-ankershoffen/starbridge/size?color=%2344cc11&tag=latest&label=size&trim=)](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/pkgs/container/starbridge)
+-->
+> ⚠️ **WARNING**: This project is currently in pre-alpha phase, i.e. partly functional. Feel free to already watch or star the repository to stay updated on its progress.

_readme_main.md

@@ -0,0 +1,70 @@
+Integrates Claude Desktop with the web, Atlassian Confluence, and (later on) Google Workspace.
+
+1. **Make Claude a team member**: Makes Claude an informed member of your organisation by accessing your organization's key knowledge resources.
+2. **Integrate research and knowlege management**: Enables your teams to contribute, refine, and maintain your organisation's knowledge resources within Claude - seamlessly integrating research and sharing knowledge.
+3. **Improve efficiency**: Automate repetitive workflows such as generating Confluence pages from Google Docs.
+
+## Qualities
+
+* [Complete reference documenation](https://starbridge.readthedocs.io/en/latest/reference_index.html) on Read the Docs
+* [High test coverage](https://app.codecov.io/gh/helmut-hoffer-von-ankershoffen/starbridge) including unit and E2E tests (reported on Codecov)
+* Matrix tested with [Python 3.11, 3.12 and 3.13](https://github.com/helmut-hoffer-von-ankershoffen/starbridge/blob/main/noxfile.py) to ensure compatibility (powered by [Nox](https://nox.thea.codes/en/stable/))
+* 100% compliant with modern linting and formatting standards (powered by [Ruff](https://github.com/astral-sh/ruff))
+* 100% up-to-date dependencies (monitored by [Renovate](https://github.com/renovatebot/renovate))
+* [A-grade code quality](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_starbridge) in security, maintainability, and reliability (verified by SonarQube)
+* 1-liner for installation and execution of command line interface (CLI) via [uv(x)](https://github.com/astral-sh/uv) or [Docker](https://hub.docker.com/r/helmuthva/starbridge/tags)
+* Setup for developing inside a [devcontainer](https://code.visualstudio.com/docs/devcontainers/containers) included (supports VSCode and GitHub Codespaces)
+
+## Example Prompts
+
+* "Create a page about road cycling, focusing on Canyon bikes, in the personal confluence space of Helmut."
+
+## Setup
+
+```uvx starbridge install``` - that's all.
+
+Prequisites:
+- You are running Mac OS X
+- You already have the uv package manager installed
+- You already have Claude Desktop for Mac OS X installed
+- You don't care for the imaging extra
+
+If you (possibly) need to install homebrew, uv, and care for all extras:
+
+```shell
+if [[ "$OSTYPE" == "darwin"* ]]; then # Install dependencies for macOS X
+  if ! command -v brew &> /dev/null; then # Install Homebrew if not present
+    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+  fi
+  brew install cairo
+elif [[ "$OSTYPE" == "linux-gnu"* ]]; then # Install dependencies for Linux
+  sudo apt-get update -y && sudo apt-get install curl libcairo2 -y
+fi
+if ! command -v uvx &> /dev/null; then # Install uv package manager if not present
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+  source $HOME/.local/bin/env
+fi
+uvx --with "starbridge[imaging]" starbridge install # Install starbridge, including configuration and injection into Claude Desktop App
+```
+
+Starbridge can be [run within Docker](https://starbridge.readthedocs.io/en/latest/docker.html).
+
+## MCP Server
+
+Starbridge implements the [MCP Server](https://modelcontextprotocol.io/docs/concepts/architecture) interface, with Claude acting as an MCP client.
+
+### Resources
+
+[TODO: Document resources exposed to Claude Desktop]
+
+### Prompts
+
+[TODO: Document prompts exposed to Claude Desktop]
+
+### Tools
+
+[TODO: Document tools exposed to Claude Desktop]
+
+## CLI
+
+[TODO: Document CLI commands]

docs/source/conf.py

@@ -1,41 +1,73 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""Sphinx configuration."""  # noqa: INP001
 
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
-project = "starbridge"
-copyright = "2025, Helmut Hoffer von Ankershoffen"
-author = "Helmut Hoffer von Ankershoffen"
-release = "0.0.67"
-github_username = "helmut-hoffer-von-ankershoffen"
-github_repository = "starbridge"
-
-# -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+import re
+from datetime import UTC, datetime
 
 extensions = [
+    "sphinx_toolbox.collapse",  # https://sphinx-toolbox.readthedocs.io/
+    "sphinx_toolbox.sidebar_links",
+    "sphinx_toolbox.github",
+    "sphinx_toolbox.source",
     "sphinx.ext.autodoc",
-    "sphinx_autodoc_typehints",
+    "enum_tools.autoenum",  # https://github.com/domdfcoding/enum_tools/tree/master
+    "sphinx.ext.napoleon",  # https://sphinxcontrib-napoleon.readthedocs.io/en/latest/
     "sphinx-pydantic",
-    "sphinxcontrib.autodoc_pydantic",
-    "enum_tools.autoenum",
-    "sphinx_copybutton",
+    "sphinxcontrib.autodoc_pydantic",  # https://autodoc-pydantic.readthedocs.io/en/stable/users/examples.html
     "sphinx.ext.coverage",
+    "sphinx_copybutton",
+    "sphinx.ext.extlinks",  # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
+    "sphinx.ext.imgconverter",
+    "sphinx_inline_tabs",
     "sphinx_mdinclude",
+    "sphinxemoji.sphinxemoji",  # https://sphinxemojicodes.readthedocs.io/en/stable/
     "sphinxext.opengraph",
-    "sphinx_inline_tabs",
-    "sphinx_toolbox",
 ]
 
-templates_path = ["_templates"]
-exclude_patterns = []
+project = "starbridge"
+author = "Helmut Hoffer von Ankershoffen"
+copyright = f" (c) 2025-{datetime.now(UTC).year}, {author}"
+version = "0.0.67"
+release = version
+github_username = "helmut-hoffer-von-ankershoffen"
+github_repository = "starbridge"
+
+language = "en"
+
+ogp_site_name = "Starbridge"
+ogp_image = "https://starbridge.readthedocs.io/en/latest/_static/starbridge.png"
+ogp_custom_meta_tags = [
+    '<meta name="twitter:card" content="Starbridge MCP Server" />',
+]
+ogp_enable_meta_description = True
+ogp_description_length = 300
+
+autodoc_pydantic_model_show_json = False
 
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = True
+napoleon_use_admonition_for_notes = True
+napoleon_use_admonition_for_references = True
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_preprocess_types = True
+napoleon_type_aliases = None
+napoleon_attr_annotations = True
 
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+linkcheck_retries = 2
+linkcheck_timeout = 1
+linkcheck_workers = 10
+linkcheck_ignore = [
+    r"http://127\.0\.0\.1",
+    r"http://localhost",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
 
 html_theme = "furo"
 html_static_path = ["_static"]
@@ -47,5 +79,48 @@
         '<a target="_blank" href="https://hub.docker.com/r/helmuthva/starbridge/tags">Docker</a> - '
         '<a target="_blank" href="https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_starbridge">SonarQube</a> - '
         '<a target="_blank" href="https://app.codecov.io/gh/helmut-hoffer-von-ankershoffen/starbridge">Codecov</a>'
-    )
+        '<a target="_blank" href="https://github.com/helmut-hoffer-von-ankershoffen/starbridge/blob/main/LICENSE">License</a>'
+    ),
+}
+
+
+latex_engine = "lualatex"  # https://github.com/readthedocs/readthedocs.org/issues/8382
+
+# If true, show page references after internal links.
+latex_show_pagerefs = True
+
+# If true, show URL addresses after external links.
+latex_show_urls = "footnote"
+
+# If false, no module index is generated.
+latex_domain_indices = True
+
+# See https://www.sphinx-doc.org/en/master/latex.html
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    "papersize": "a4paper",
+    # The font size ('10pt', '11pt' or '12pt').
+    "pointsize": "10pt",
+    # https://github.com/sphinx-doc/sphinx/issues/12332.
+    "preamble": r"""
+\directlua {
+  luaotfload.add_fallback("emoji",
+  {
+     "[TwemojiMozilla.ttf]:mode=harf;",
+     "[DejaVuSans.ttf]:mode=harf;",
+  }
+  )
+}
+\setmainfont{LatinModernRoman}[RawFeature={fallback=emoji},SmallCapsFont={* Caps}]
+\setsansfont{LatinModernSans}[RawFeature={fallback=emoji}]
+\setmonofont{DejaVuSansMono}[RawFeature={fallback=emoji},Scale=0.8]
+    """,
 }
+
+slug = re.sub(r"\W+", "-", project.lower())
+
+latex_documents = [
+    ("index", f"{slug}.tex", rf"{project} Documentation", author, "manual", False),
+]
+
+latex_logo = "../../starbridge.png"

docs/source/index.rst

@@ -1,23 +1,37 @@
-.. brave-search-python-client documentation master file, created by
-   sphinx-quickstart on Thu Jan  2 09:10:01 2025.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. only:: html
 
-.. mdinclude:: ../../README.md
+   .. include:: main.rst
+.. toctree::
+	:hidden:
+
+	Home<self>
 
 .. toctree::
    :maxdepth: 2
 
-   readme
+   main
    docker
+   reference
+   release-notes
    contributing
-   reference_index
-   changelog
 
 
-Indices and tables
-==================
+.. sidebar-links::
+   :caption: Links
+   :github:
+   :pypi: starbridge
+
+   Docker <https://hub.docker.com/r/helmuthva/starbridge/tags>
+   SonarQube <https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_starbridge>
+   Codecov <https://app.codecov.io/gh/helmut-hoffer-von-ankershoffen/starbridge>
+   ghcr.io <https://github.com/helmut-hoffer-von-ankershoffen/starbridge/pkgs/container/starbridge>
+   License <https://github.com/helmut-hoffer-von-ankershoffen/starbridge/blob/main/LICENSE>
+
+.. only:: html
+
+   Indices and tables
+   ==================
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   * :ref:`genindex`
+   * :ref:`modindex`
+   * :ref:`search`

docs/source/main.rst

@@ -0,0 +1,2 @@
+.. mdinclude:: ../../_readme_main.md
+    :start-line: 0