mkdocs2confluence 0.8.0__tar.gz → 0.8.2__tar.gz

{mkdocs2confluence-0.8.0 → mkdocs2confluence-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.8.0
+Version: 0.8.2
 Summary: Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more
 Author: Anders Hybertz
 License: GPL-3.0-or-later
@@ -54,6 +54,8 @@ Dynamic: license-file
 
 A Python CLI tool that compiles MkDocs-flavoured Markdown into native Confluence storage XHTML and publishes it directly to Confluence Cloud. It is a **compiler/transpiler**, not an HTML converter — every construct maps to its native Confluence equivalent, so pages look and behave like hand-authored Confluence content.
 
+It also bridges the gap between Confluence reviewers and developers: the `sync-comments` command turns open Confluence page comments into GitHub pull request review threads, and auto-resolves them in Confluence when the PR is merged.
+
 > **Zensical compatible** — [Zensical](https://zensical.org/) is the modern successor to MkDocs + Material for MkDocs. Since it uses the same `mkdocs.yml` format and Python Markdown extensions, your Zensical project works with mk2conf today with no changes required.
 
 ---
@@ -109,6 +111,12 @@ mk2conf publish
 
 # Export a nav section to a stand-alone PDF document
 mk2conf pdf --section Guide --out guide.pdf
+
+# Sync open Confluence comments to GitHub review PRs
+mk2conf sync-comments
+
+# Resolve Confluence comments when their review PRs are merged
+mk2conf sync-comments --check-merges
 ```
 
 ---
@@ -128,12 +136,32 @@ confluence:
   full_width: true                   # default: true
 ```
 
+The `confluence:` block is also accepted under `extra:` (MkDocs strict-mode compatible):
+
+```yaml
+extra:
+  confluence:
+    base_url: https://yourorg.atlassian.net
+    space_key: TECH
+    ...
+```
+
 The API token is read from (in priority order):
 
 1. `token:` in `mkdocs.yml` — typically via `!ENV CONFLUENCE_API_TOKEN`
 2. `CONFLUENCE_API_TOKEN` environment variable
 3. `MK2CONF_TOKEN` environment variable
 
+### Additional fields for `sync-comments`
+
+```yaml
+confluence:
+  # ... base fields above ...
+  github_repo: owner/repo        # required for sync-comments
+  github_token: !ENV GITHUB_TOKEN  # falls back to GITHUB_TOKEN env var
+  github_base_branch: main       # default: main
+```
+
 ---
 
 ## Your first publish
@@ -286,14 +314,14 @@ mk2conf sync-comments [--config PATH] [--check-merges] [--force] [--dry-run] [--
 | `--dry-run` | off | Print what would be synced without making any API calls |
 | `--quiet` | off | Suppress progress output |
 
-**Required config** (under `extra.confluence` in `mkdocs.yml`):
+**Required config** (add to the `confluence:` block in `mkdocs.yml`):
 
 ```yaml
-extra:
-  confluence:
-    github_repo: owner/repo        # required for sync-comments
-    github_token: ${GITHUB_TOKEN}  # falls back to GITHUB_TOKEN env var
-    github_base_branch: main       # default: main
+confluence:
+  # ... base fields ...
+  github_repo: owner/repo            # required for sync-comments
+  github_token: !ENV GITHUB_TOKEN    # falls back to GITHUB_TOKEN env var
+  github_base_branch: main           # default: main
 ```
 
 **Workflow:**
@@ -421,6 +449,8 @@ MkDocs abbreviation definitions (`*[ABBR]: Full term`) are rendered as inline su
 
 Each stage is a separate Python module under `src/mkdocs_to_confluence/`. The **plan** phase makes all API read calls (find existing pages); the **execute** phase makes all write calls, ensuring parent pages always exist before their children.
 
+The `sync/` package is a self-contained pipeline for the `sync-comments` command: it fetches Confluence comments, anchors them to source lines, posts them as GitHub review threads via GraphQL, and resolves them on PR merge. The `ReviewPlatformClient` Protocol keeps GitHub-specific code isolated so future GitLab or Azure DevOps adapters slot in without touching the core.
+
 ---
 
 ## Development

{mkdocs2confluence-0.8.0 → mkdocs2confluence-0.8.2}/README.md

@@ -14,6 +14,8 @@
 
 A Python CLI tool that compiles MkDocs-flavoured Markdown into native Confluence storage XHTML and publishes it directly to Confluence Cloud. It is a **compiler/transpiler**, not an HTML converter — every construct maps to its native Confluence equivalent, so pages look and behave like hand-authored Confluence content.
 
+It also bridges the gap between Confluence reviewers and developers: the `sync-comments` command turns open Confluence page comments into GitHub pull request review threads, and auto-resolves them in Confluence when the PR is merged.
+
 > **Zensical compatible** — [Zensical](https://zensical.org/) is the modern successor to MkDocs + Material for MkDocs. Since it uses the same `mkdocs.yml` format and Python Markdown extensions, your Zensical project works with mk2conf today with no changes required.
 
 ---
@@ -69,6 +71,12 @@ mk2conf publish
 
 # Export a nav section to a stand-alone PDF document
 mk2conf pdf --section Guide --out guide.pdf
+
+# Sync open Confluence comments to GitHub review PRs
+mk2conf sync-comments
+
+# Resolve Confluence comments when their review PRs are merged
+mk2conf sync-comments --check-merges
 ```
 
 ---
@@ -88,12 +96,32 @@ confluence:
   full_width: true                   # default: true
 ```
 
+The `confluence:` block is also accepted under `extra:` (MkDocs strict-mode compatible):
+
+```yaml
+extra:
+  confluence:
+    base_url: https://yourorg.atlassian.net
+    space_key: TECH
+    ...
+```
+
 The API token is read from (in priority order):
 
 1. `token:` in `mkdocs.yml` — typically via `!ENV CONFLUENCE_API_TOKEN`
 2. `CONFLUENCE_API_TOKEN` environment variable
 3. `MK2CONF_TOKEN` environment variable
 
+### Additional fields for `sync-comments`
+
+```yaml
+confluence:
+  # ... base fields above ...
+  github_repo: owner/repo        # required for sync-comments
+  github_token: !ENV GITHUB_TOKEN  # falls back to GITHUB_TOKEN env var
+  github_base_branch: main       # default: main
+```
+
 ---
 
 ## Your first publish
@@ -246,14 +274,14 @@ mk2conf sync-comments [--config PATH] [--check-merges] [--force] [--dry-run] [--
 | `--dry-run` | off | Print what would be synced without making any API calls |
 | `--quiet` | off | Suppress progress output |
 
-**Required config** (under `extra.confluence` in `mkdocs.yml`):
+**Required config** (add to the `confluence:` block in `mkdocs.yml`):
 
 ```yaml
-extra:
-  confluence:
-    github_repo: owner/repo        # required for sync-comments
-    github_token: ${GITHUB_TOKEN}  # falls back to GITHUB_TOKEN env var
-    github_base_branch: main       # default: main
+confluence:
+  # ... base fields ...
+  github_repo: owner/repo            # required for sync-comments
+  github_token: !ENV GITHUB_TOKEN    # falls back to GITHUB_TOKEN env var
+  github_base_branch: main           # default: main
 ```
 
 **Workflow:**
@@ -381,6 +409,8 @@ MkDocs abbreviation definitions (`*[ABBR]: Full term`) are rendered as inline su
 
 Each stage is a separate Python module under `src/mkdocs_to_confluence/`. The **plan** phase makes all API read calls (find existing pages); the **execute** phase makes all write calls, ensuring parent pages always exist before their children.
 
+The `sync/` package is a self-contained pipeline for the `sync-comments` command: it fetches Confluence comments, anchors them to source lines, posts them as GitHub review threads via GraphQL, and resolves them on PR merge. The `ReviewPlatformClient` Protocol keeps GitHub-specific code isolated so future GitLab or Azure DevOps adapters slot in without touching the core.
+
 ---
 
 ## Development

{mkdocs2confluence-0.8.0 → mkdocs2confluence-0.8.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs2confluence"
-version = "0.8.0"
+version = "0.8.2"
 description = "Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more"
 readme = "README.md"
 license = { text = "GPL-3.0-or-later" }

{mkdocs2confluence-0.8.0 → mkdocs2confluence-0.8.2}/src/mkdocs2confluence.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.8.0
+Version: 0.8.2
 Summary: Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more
 Author: Anders Hybertz
 License: GPL-3.0-or-later
@@ -54,6 +54,8 @@ Dynamic: license-file
 
 A Python CLI tool that compiles MkDocs-flavoured Markdown into native Confluence storage XHTML and publishes it directly to Confluence Cloud. It is a **compiler/transpiler**, not an HTML converter — every construct maps to its native Confluence equivalent, so pages look and behave like hand-authored Confluence content.
 
+It also bridges the gap between Confluence reviewers and developers: the `sync-comments` command turns open Confluence page comments into GitHub pull request review threads, and auto-resolves them in Confluence when the PR is merged.
+
 > **Zensical compatible** — [Zensical](https://zensical.org/) is the modern successor to MkDocs + Material for MkDocs. Since it uses the same `mkdocs.yml` format and Python Markdown extensions, your Zensical project works with mk2conf today with no changes required.
 
 ---
@@ -109,6 +111,12 @@ mk2conf publish
 
 # Export a nav section to a stand-alone PDF document
 mk2conf pdf --section Guide --out guide.pdf
+
+# Sync open Confluence comments to GitHub review PRs
+mk2conf sync-comments
+
+# Resolve Confluence comments when their review PRs are merged
+mk2conf sync-comments --check-merges
 ```
 
 ---
@@ -128,12 +136,32 @@ confluence:
   full_width: true                   # default: true
 ```
 
+The `confluence:` block is also accepted under `extra:` (MkDocs strict-mode compatible):
+
+```yaml
+extra:
+  confluence:
+    base_url: https://yourorg.atlassian.net
+    space_key: TECH
+    ...
+```
+
 The API token is read from (in priority order):
 
 1. `token:` in `mkdocs.yml` — typically via `!ENV CONFLUENCE_API_TOKEN`
 2. `CONFLUENCE_API_TOKEN` environment variable
 3. `MK2CONF_TOKEN` environment variable
 
+### Additional fields for `sync-comments`
+
+```yaml
+confluence:
+  # ... base fields above ...
+  github_repo: owner/repo        # required for sync-comments
+  github_token: !ENV GITHUB_TOKEN  # falls back to GITHUB_TOKEN env var
+  github_base_branch: main       # default: main
+```
+
 ---
 
 ## Your first publish
@@ -286,14 +314,14 @@ mk2conf sync-comments [--config PATH] [--check-merges] [--force] [--dry-run] [--
 | `--dry-run` | off | Print what would be synced without making any API calls |
 | `--quiet` | off | Suppress progress output |
 
-**Required config** (under `extra.confluence` in `mkdocs.yml`):
+**Required config** (add to the `confluence:` block in `mkdocs.yml`):
 
 ```yaml
-extra:
-  confluence:
-    github_repo: owner/repo        # required for sync-comments
-    github_token: ${GITHUB_TOKEN}  # falls back to GITHUB_TOKEN env var
-    github_base_branch: main       # default: main
+confluence:
+  # ... base fields ...
+  github_repo: owner/repo            # required for sync-comments
+  github_token: !ENV GITHUB_TOKEN    # falls back to GITHUB_TOKEN env var
+  github_base_branch: main           # default: main
 ```
 
 **Workflow:**
@@ -421,6 +449,8 @@ MkDocs abbreviation definitions (`*[ABBR]: Full term`) are rendered as inline su
 
 Each stage is a separate Python module under `src/mkdocs_to_confluence/`. The **plan** phase makes all API read calls (find existing pages); the **execute** phase makes all write calls, ensuring parent pages always exist before their children.
 
+The `sync/` package is a self-contained pipeline for the `sync-comments` command: it fetches Confluence comments, anchors them to source lines, posts them as GitHub review threads via GraphQL, and resolves them on PR merge. The `ReviewPlatformClient` Protocol keeps GitHub-specific code isolated so future GitLab or Azure DevOps adapters slot in without touching the core.
+
 ---
 
 ## Development

{mkdocs2confluence-0.8.0 → mkdocs2confluence-0.8.2}/src/mkdocs_to_confluence/cli.py

@@ -548,25 +548,33 @@ def _cmd_publish(args: argparse.Namespace) -> None:
     print(str(report))
 
     # Write page map so sync-comments can match source files to Confluence pages.
-    if not (getattr(args, "page", None) or getattr(args, "section", None)):
-        import json as _json_pm
+    # Always merge into the existing map so partial runs (--page/--section) and
+    # multiple configs pointing to the same repo root all accumulate correctly.
+    import json as _json_pm
+    try:
+        repo_root = config_path.parent
         try:
-            repo_root = config_path.parent
+            docs_rel = config.docs_dir.relative_to(repo_root)
+        except ValueError:
+            docs_rel = Path("docs")
+        new_entries = {
+            str(docs_rel / action.node.docs_path): action.page_id
+            for action in plan
+            if action.node.docs_path and action.page_id and not action.is_folder
+        }
+        pm_path = repo_root / ".mk2conf-pages.json"
+        existing: dict[str, str] = {}
+        if pm_path.exists():
             try:
-                docs_rel = config.docs_dir.relative_to(repo_root)
-            except ValueError:
-                docs_rel = Path("docs")
-            page_map = {
-                str(docs_rel / action.node.docs_path): action.page_id
-                for action in plan
-                if action.node.docs_path and action.page_id and not action.is_folder
-            }
-            pm_path = repo_root / ".mk2conf-pages.json"
-            pm_path.write_text(_json_pm.dumps(page_map, indent=2), encoding="utf-8")
-            if not getattr(args, "quiet", False):
-                print(f"Page map: {len(page_map)} page(s) → {pm_path.name}")
-        except Exception as exc:
-            print(f"  [warn] could not write page map: {exc}", file=sys.stderr)
+                existing = _json_pm.loads(pm_path.read_text(encoding="utf-8"))
+            except Exception:
+                pass
+        existing.update(new_entries)
+        pm_path.write_text(_json_pm.dumps(existing, indent=2), encoding="utf-8")
+        if not getattr(args, "quiet", False):
+            print(f"Page map: {len(existing)} page(s) → {pm_path.name}")
+    except Exception as exc:
+        print(f"  [warn] could not write page map: {exc}", file=sys.stderr)
 
     if getattr(args, "report", None):
         import json as _json

{mkdocs2confluence-0.8.0 → mkdocs2confluence-0.8.2}/src/mkdocs_to_confluence/sync/platform.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from typing import Protocol
 
 
-class ReviewPlatformClient(Protocol):
+class ReviewPlatformClient(Protocol):  # pragma: no cover
     """Interface for posting review comments on a hosted git platform.
 
     Implement this protocol to add support for GitLab, Azure DevOps, etc.