How senges/tovald works
Purpose and Entry Points
Tovald is a Python CLI that publishes a directory tree of Markdown documentation to a Confluence space. The executable entry path is tovald/main.py; package metadata and runtime dependencies are defined in pyproject.toml. Invocation accepts a documentation root and an optional cleanup mode.
CLI Orchestration
tovald/main.py reads CLI arguments and environment-based Confluence settings, then drives compilation and publication. tovald/conf.py centralizes generated Sphinx/Confluence configuration, keeping runtime credentials and publication policy separate from source Markdown.
Documentation Tree Contract
The input boundary is a filesystem tree in which each Confluence page is a directory containing index.md; optional .assets directories hold page-local static files. The compiler must preserve directory hierarchy as a Confluence page hierarchy and derive page titles from top-level Markdown headings. Fixture trees demonstrate valid and invalid structural cases under tests/static/valid_tree/doc and tests/static/missing_index_tree/doc.
Compilation Stage
tovald/compiler/main.py transforms the source documentation tree into a Sphinx-compatible intermediate project. This includes validating page structure, generating navigation/toctree material from the directory tree, and preparing content/assets for Sphinx processing. Its package boundary is tovald/compiler/__init__.py; the generated toctree template is tovald/static/toctree.j2.
Sphinx-to-Confluence Publication
The generated Sphinx project is configured to use MyST Markdown parsing and sphinxcontrib-confluencebuilder, which renders pages and calls Confluence using the configured server URL, space key, parent page, PAT, source URL, and optional page-name prefix. Sphinx/Confluence output is an external-service boundary; Tovald primarily supplies project structure and configuration rather than implementing rendering or Confluence API behavior itself.
Cleanup Control Path
The --cleanup flag in tovald/main.py represents a distinct publication-management path, intended to remove or reconcile previously published pages rather than merely compile and publish current content. It shares the Confluence configuration boundary in tovald/conf.py.
Runtime and Delivery
The project runs on Python and is packaged for direct installation or uv execution (pyproject.toml, uv.lock). A containerized runtime is defined by Dockerfile. GitHub Actions provide lint/test and image/package build-publish pipelines: .github/workflows/lint-and-test.yml, .github/workflows/docker-build.yml, and .github/workflows/build-and-publish.yml.
Main entry points: tovald/main.py CLI entry point · compiler/main.py Documentation compiler · pyproject.toml Package definition · conf.py Confluence configuration
Components 18
Runtime
- CLI entry point · Reads arguments and environment settings; selects publish or cleanup.
tovald/main.py - Package definition · Defines metadata and runtime dependencies.
pyproject.toml - Container runtime
Dockerfile
Compilation
- Compiler package
tovald/compiler/__init__.py - Documentation compiler · Validates structure and creates a Sphinx-compatible project.
tovald/compiler/main.py - Toctree template
tovald/static/toctree.j2 - Generated Sphinx project · Contains prepared Markdown, assets, and generated navigation.
Publication
- Confluence configuration · Supplies publication policy and runtime credentials.
tovald/conf.py - Sphinx + MyST · Parses generated Markdown and renders Confluence content.
- Confluence builder · Publishes rendered pages using configured Confluence settings.
- Confluence space · Receives the directory-derived page hierarchy.
- Cleanup operation · Removes or reconciles previously published pages.
tovald/main.py
Delivery
- Lint and test workflow
.github/workflows/lint-and-test.yml - Docker build workflow
.github/workflows/docker-build.yml - Package publish workflow
.github/workflows/build-and-publish.yml
Other components
- Markdown documentation tree · Each page directory requires index.md; .assets is optional.
- Valid tree fixture
tests/static/valid_tree/doc - Missing-index fixture
tests/static/missing_index_tree/doc
Connections 20
- Valid tree fixture → Markdown documentation tree: demonstrates
- Missing-index fixture → Markdown documentation tree: tests invalid contract
- Package definition → CLI entry point: installs runtime
- Container runtime → CLI entry point: runs
- CLI entry point → Compiler package: invokes
- Compiler package → Documentation compiler: exposes
- Markdown documentation tree → Documentation compiler: source input
- Toctree template → Documentation compiler: generates navigation
- Documentation compiler → Generated Sphinx project: builds
- CLI entry point → Confluence configuration: loads settings
- Generated Sphinx project → Sphinx + MyST: renders
- Confluence configuration → Confluence builder: configures
- Sphinx + MyST → Confluence builder: uses extension
- Confluence builder → Confluence space: publishes pages
- CLI entry point → Cleanup operation: --cleanup
- Cleanup operation → Confluence configuration: uses settings
- Cleanup operation → Confluence space: reconciles pages
- Lint and test workflow → Package definition: validates
- Docker build workflow → Container runtime: builds image
- Package publish workflow → Package definition: builds and publishes