mkdocs2confluence 0.7.37__tar.gz → 0.8.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.7.37
+Version: 0.8.0
 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
@@ -270,6 +270,48 @@ The PDF includes a **cover page**, **table of contents** with page numbers, and
 
 ---
 
+### `mk2conf sync-comments`
+
+Bridge Confluence page/inline comments to GitHub pull request review threads. Non-technical reviewers comment in Confluence; developers address feedback on a GitHub feature branch; Confluence comments are auto-resolved when the PR is merged.
+
+```
+mk2conf sync-comments [--config PATH] [--check-merges] [--force] [--dry-run] [--quiet]
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--config PATH` | `./mkdocs.yml` | Path to `mkdocs.yml` |
+| `--check-merges` | off | Check tracked PRs for merges and auto-resolve Confluence comments |
+| `--force` | off | Re-sync pages that already have an open review PR |
+| `--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`):
+
+```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
+```
+
+**Workflow:**
+
+1. Run `mk2conf publish` first — generates `.mk2conf-pages.json` mapping source files to Confluence page IDs.
+2. Run `mk2conf sync-comments` — for each page with open Confluence comments, creates a `mk2conf/review/{slug}` branch and PR, then posts each comment as a GitHub review thread. Inline comments with a text selection are anchored to the matching source line; page-level comments fall back to file-level review threads. Every thread body includes a **View in Confluence** deep-link that opens Confluence focused on the exact comment.
+3. Developer addresses feedback on the branch, pushes changes, and merges the PR.
+4. Run `mk2conf sync-comments --check-merges` — detects merged PRs, adds a resolution reply to each Confluence comment with the commit info, and marks the comments as resolved.
+
+**State files** (add to `.gitignore`):
+
+| File | Purpose |
+|---|---|
+| `.mk2conf-pages.json` | Source path → Confluence page ID map, written after each `publish` |
+| `.mk2conf-sync-state.json` | Tracks open/merged review PRs and their associated comment IDs |
+
+---
+
 ## Supported Markdown features
 
 ### Block elements

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

@@ -230,6 +230,48 @@ The PDF includes a **cover page**, **table of contents** with page numbers, and
 
 ---
 
+### `mk2conf sync-comments`
+
+Bridge Confluence page/inline comments to GitHub pull request review threads. Non-technical reviewers comment in Confluence; developers address feedback on a GitHub feature branch; Confluence comments are auto-resolved when the PR is merged.
+
+```
+mk2conf sync-comments [--config PATH] [--check-merges] [--force] [--dry-run] [--quiet]
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--config PATH` | `./mkdocs.yml` | Path to `mkdocs.yml` |
+| `--check-merges` | off | Check tracked PRs for merges and auto-resolve Confluence comments |
+| `--force` | off | Re-sync pages that already have an open review PR |
+| `--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`):
+
+```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
+```
+
+**Workflow:**
+
+1. Run `mk2conf publish` first — generates `.mk2conf-pages.json` mapping source files to Confluence page IDs.
+2. Run `mk2conf sync-comments` — for each page with open Confluence comments, creates a `mk2conf/review/{slug}` branch and PR, then posts each comment as a GitHub review thread. Inline comments with a text selection are anchored to the matching source line; page-level comments fall back to file-level review threads. Every thread body includes a **View in Confluence** deep-link that opens Confluence focused on the exact comment.
+3. Developer addresses feedback on the branch, pushes changes, and merges the PR.
+4. Run `mk2conf sync-comments --check-merges` — detects merged PRs, adds a resolution reply to each Confluence comment with the commit info, and marks the comments as resolved.
+
+**State files** (add to `.gitignore`):
+
+| File | Purpose |
+|---|---|
+| `.mk2conf-pages.json` | Source path → Confluence page ID map, written after each `publish` |
+| `.mk2conf-sync-state.json` | Tracks open/merged review PRs and their associated comment IDs |
+
+---
+
 ## Supported Markdown features
 
 ### Block elements

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

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs2confluence"
-version = "0.7.37"
+version = "0.8.0"
 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.7.37 → mkdocs2confluence-0.8.0}/src/mkdocs2confluence.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.7.37
+Version: 0.8.0
 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
@@ -270,6 +270,48 @@ The PDF includes a **cover page**, **table of contents** with page numbers, and
 
 ---
 
+### `mk2conf sync-comments`
+
+Bridge Confluence page/inline comments to GitHub pull request review threads. Non-technical reviewers comment in Confluence; developers address feedback on a GitHub feature branch; Confluence comments are auto-resolved when the PR is merged.
+
+```
+mk2conf sync-comments [--config PATH] [--check-merges] [--force] [--dry-run] [--quiet]
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--config PATH` | `./mkdocs.yml` | Path to `mkdocs.yml` |
+| `--check-merges` | off | Check tracked PRs for merges and auto-resolve Confluence comments |
+| `--force` | off | Re-sync pages that already have an open review PR |
+| `--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`):
+
+```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
+```
+
+**Workflow:**
+
+1. Run `mk2conf publish` first — generates `.mk2conf-pages.json` mapping source files to Confluence page IDs.
+2. Run `mk2conf sync-comments` — for each page with open Confluence comments, creates a `mk2conf/review/{slug}` branch and PR, then posts each comment as a GitHub review thread. Inline comments with a text selection are anchored to the matching source line; page-level comments fall back to file-level review threads. Every thread body includes a **View in Confluence** deep-link that opens Confluence focused on the exact comment.
+3. Developer addresses feedback on the branch, pushes changes, and merges the PR.
+4. Run `mk2conf sync-comments --check-merges` — detects merged PRs, adds a resolution reply to each Confluence comment with the commit info, and marks the comments as resolved.
+
+**State files** (add to `.gitignore`):
+
+| File | Purpose |
+|---|---|
+| `.mk2conf-pages.json` | Source path → Confluence page ID map, written after each `publish` |
+| `.mk2conf-sync-state.json` | Tracks open/merged review PRs and their associated comment IDs |
+
+---
+
 ## Supported Markdown features
 
 ### Block elements

{mkdocs2confluence-0.7.37 → mkdocs2confluence-0.8.0}/src/mkdocs2confluence.egg-info/SOURCES.txt

@@ -38,6 +38,13 @@ src/mkdocs_to_confluence/preview/server.py
 src/mkdocs_to_confluence/publisher/__init__.py
 src/mkdocs_to_confluence/publisher/client.py
 src/mkdocs_to_confluence/publisher/pipeline.py
+src/mkdocs_to_confluence/sync/__init__.py
+src/mkdocs_to_confluence/sync/anchoring.py
+src/mkdocs_to_confluence/sync/command.py
+src/mkdocs_to_confluence/sync/comments.py
+src/mkdocs_to_confluence/sync/github.py
+src/mkdocs_to_confluence/sync/platform.py
+src/mkdocs_to_confluence/sync/state.py
 src/mkdocs_to_confluence/transforms/__init__.py
 src/mkdocs_to_confluence/transforms/abbrevs.py
 src/mkdocs_to_confluence/transforms/assets.py
@@ -67,4 +74,9 @@ tests/test_publish_client.py
 tests/test_publish_config.py
 tests/test_publish_pipeline.py
 tests/test_server.py
+tests/test_sync_anchoring.py
+tests/test_sync_command.py
+tests/test_sync_comments.py
+tests/test_sync_github.py
+tests/test_sync_state.py
 tests/test_treeutil.py

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

@@ -223,6 +223,48 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Suppress per-item progress output.",
     )
 
+    # --- sync-comments ---
+    sc = sub.add_parser(
+        "sync-comments",
+        help="Sync open Confluence comments to GitHub review PRs.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Requires github_repo and github_token (or GITHUB_TOKEN env var) in mkdocs.yml.\n"
+            "\n"
+            "Examples:\n"
+            "  mk2conf sync-comments                     # sync new comments → PRs\n"
+            "  mk2conf sync-comments --check-merges      # resolve merged PRs in Confluence\n"
+            "  mk2conf sync-comments --dry-run           # preview without making changes\n"
+        ),
+    )
+    sc.add_argument(
+        "--config",
+        metavar="PATH",
+        default="mkdocs.yml",
+        help="Path to mkdocs.yml (default: ./mkdocs.yml).",
+    )
+    sc.add_argument(
+        "--check-merges",
+        action="store_true",
+        help="Check tracked PRs for merges and resolve their Confluence comments.",
+    )
+    sc.add_argument(
+        "--force",
+        action="store_true",
+        help="Re-sync pages that already have an open review PR.",
+    )
+    sc.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print what would be synced without creating branches, PRs, or review threads.",
+    )
+    sc.add_argument(
+        "--quiet",
+        "-q",
+        action="store_true",
+        help="Suppress progress output.",
+    )
+
     return parser
 
 
@@ -244,6 +286,8 @@ def main(argv: list[str] | None = None) -> None:
             _cmd_publish(args)
         elif args.command == "pdf":
             _cmd_pdf(args)
+        elif args.command == "sync-comments":
+            _cmd_sync_comments(args)
     except (ValueError, FileNotFoundError) as exc:
         print(f"error: {exc}", file=sys.stderr)
         sys.exit(1)
@@ -503,6 +547,27 @@ 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
+        try:
+            repo_root = config_path.parent
+            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)
+
     if getattr(args, "report", None):
         import json as _json
 
@@ -612,3 +677,61 @@ def _cmd_pdf(args: argparse.Namespace) -> None:
         sys.exit(1)
 
     print(f"PDF written to {out_path}")
+
+
+def _cmd_sync_comments(args: argparse.Namespace) -> None:
+    from mkdocs_to_confluence.publisher.client import ConfluenceClient, ConfluenceError
+    from mkdocs_to_confluence.sync.command import check_and_resolve_merges, run_sync_comments
+    from mkdocs_to_confluence.sync.github import GitHubReviewClient
+
+    config_path = Path(args.config).resolve()
+    config = load_config(config_path)
+
+    conf = config.confluence
+    if conf is None:
+        print("error: no 'confluence:' section in mkdocs.yml", file=sys.stderr)
+        sys.exit(1)
+
+    if not conf.token:
+        print("error: Confluence API token not set. Set CONFLUENCE_API_TOKEN env var.", file=sys.stderr)
+        sys.exit(1)
+
+    if not conf.github_repo:
+        print(
+            "error: 'confluence.github_repo' is required for sync-comments (e.g. 'owner/repo').",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if not conf.github_token:
+        print(
+            "error: GitHub token not set. Set GITHUB_TOKEN env var or 'confluence.github_token' in mkdocs.yml.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    review_client = GitHubReviewClient(conf.github_repo, conf.github_token)
+    config_dir = config_path.parent
+
+    try:
+        with ConfluenceClient(conf) as confluence_client:
+            if args.check_merges:
+                check_and_resolve_merges(
+                    config_dir=config_dir,
+                    confluence_client=confluence_client,
+                    review_client=review_client,
+                    quiet=args.quiet,
+                )
+            else:
+                run_sync_comments(
+                    config=config,
+                    config_dir=config_dir,
+                    confluence_client=confluence_client,
+                    review_client=review_client,
+                    force=args.force,
+                    dry_run=args.dry_run,
+                    quiet=args.quiet,
+                )
+    except ConfluenceError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        sys.exit(1)

{mkdocs2confluence-0.7.37 → mkdocs2confluence-0.8.0}/src/mkdocs_to_confluence/loader/config.py

@@ -30,6 +30,9 @@ class ConfluenceConfig:
     full_width: bool = True  # set full-width layout on every published page
     nav_file: str = ".pages"  # awesome-pages filename (default: .pages, can be .nav etc.)
     mermaid_render: str = "kroki"  # "kroki", "kroki:<url>", or "none"
+    github_repo: str | None = None          # "owner/repo" — required for sync-comments
+    github_token: str | None = None         # GitHub PAT (falls back to GITHUB_TOKEN env var)
+    github_base_branch: str = "main"        # base branch for review PRs
 
 
 @dataclass(frozen=True)
@@ -241,6 +244,10 @@ def load_config(mkdocs_yml: Path) -> MkDocsConfig:
             full_width=bool(raw_conf.get("full_width", True)),
             nav_file=str(raw_conf.get("nav_file", ".pages")),
             mermaid_render=str(raw_conf.get("mermaid_render", "kroki")),
+            github_repo=str(raw_conf["github_repo"]) if raw_conf.get("github_repo") else None,
+            github_token=(str(raw_conf["github_token"]) if raw_conf.get("github_token")
+                          else os.environ.get("GITHUB_TOKEN") or None),
+            github_base_branch=str(raw_conf.get("github_base_branch", "main")),
         )
 
     # --- extra_css (optional) ---

{mkdocs2confluence-0.7.37 → mkdocs2confluence-0.8.0}/src/mkdocs_to_confluence/publisher/client.py

@@ -538,3 +538,85 @@ class ConfluenceClient:
         """Permanently delete *page_id* from Confluence."""
         resp = self._http.delete(self._v2(f"/pages/{page_id}"))
         self._raise_for_status(resp, f"delete_page({page_id!r})")
+
+    # ── Comments ───────────────────────────────────────────────────────────────
+
+    def get_page_inline_comments(self, page_id: str) -> list[dict[str, Any]]:
+        """Return all open inline comments for *page_id* (paginated)."""
+        results: list[dict[str, Any]] = []
+        url = self._v2(f"/pages/{page_id}/inline-comments")
+        params: dict[str, Any] = {"resolution-status": "open", "body-format": "storage", "limit": 250}
+        while True:
+            resp = self._http.get(url, params=params)
+            self._raise_for_status(resp, f"get_page_inline_comments({page_id!r})")
+            data = resp.json()
+            results.extend(data.get("results", []))
+            next_url = data.get("_links", {}).get("next")
+            if not next_url:
+                break
+            url = self._v2(f"/pages/{page_id}/inline-comments")
+            params = {"resolution-status": "open", "body-format": "storage",
+                      "limit": 250, "cursor": _extract_cursor(next_url)}
+        return results
+
+    def get_page_footer_comments(self, page_id: str) -> list[dict[str, Any]]:
+        """Return all open footer comments for *page_id* (paginated)."""
+        results: list[dict[str, Any]] = []
+        url = self._v2(f"/pages/{page_id}/footer-comments")
+        params: dict[str, Any] = {"resolution-status": "open", "body-format": "storage", "limit": 250}
+        while True:
+            resp = self._http.get(url, params=params)
+            self._raise_for_status(resp, f"get_page_footer_comments({page_id!r})")
+            data = resp.json()
+            results.extend(data.get("results", []))
+            next_url = data.get("_links", {}).get("next")
+            if not next_url:
+                break
+            url = self._v2(f"/pages/{page_id}/footer-comments")
+            params = {"resolution-status": "open", "body-format": "storage",
+                      "limit": 250, "cursor": _extract_cursor(next_url)}
+        return results
+
+    def add_comment_reply(self, comment_id: str, reply_text: str) -> None:
+        """Post a reply to *comment_id* using the v1 content API."""
+        url = self._v1(f"/content/{comment_id}/child/comment")
+        resp = self._http.post(url, json={
+            "type": "comment",
+            "body": {
+                "storage": {
+                    "value": f"<p>{reply_text}</p>",
+                    "representation": "storage",
+                }
+            },
+        })
+        self._raise_for_status(resp, f"add_comment_reply({comment_id!r})")
+
+    def resolve_inline_comment(self, comment_id: str) -> None:
+        """Resolve an inline comment by setting *resolved=true*."""
+        url = self._v2(f"/inline-comments/{comment_id}")
+        get_resp = self._http.get(url, params={"body-format": "storage"})
+        self._raise_for_status(get_resp, f"get_inline_comment({comment_id!r})")
+        data = get_resp.json()
+        version = data.get("version", {}).get("number", 1)
+        body_value = data.get("body", {}).get("storage", {}).get("value", "")
+        resp = self._http.put(url, json={
+            "version": {"number": version + 1},
+            "resolved": True,
+            "body": {"representation": "storage", "value": body_value},
+        })
+        self._raise_for_status(resp, f"resolve_inline_comment({comment_id!r})")
+
+    def resolve_footer_comment(self, comment_id: str) -> None:
+        """Resolve a footer comment by setting *resolved=true*."""
+        url = self._v2(f"/footer-comments/{comment_id}")
+        get_resp = self._http.get(url, params={"body-format": "storage"})
+        self._raise_for_status(get_resp, f"get_footer_comment({comment_id!r})")
+        data = get_resp.json()
+        version = data.get("version", {}).get("number", 1)
+        body_value = data.get("body", {}).get("storage", {}).get("value", "")
+        resp = self._http.put(url, json={
+            "version": {"number": version + 1},
+            "resolved": True,
+            "body": {"representation": "storage", "value": body_value},
+        })
+        self._raise_for_status(resp, f"resolve_footer_comment({comment_id!r})")

mkdocs2confluence-0.8.0/src/mkdocs_to_confluence/sync/__init__.py

@@ -0,0 +1 @@
+"""Confluence ↔ GitHub comment synchronisation."""

mkdocs2confluence-0.8.0/src/mkdocs_to_confluence/sync/anchoring.py

@@ -0,0 +1,25 @@
+"""Map Confluence inlineOriginalSelection text to a source file line number."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def find_anchor_line(source_path: Path, selection_text: str) -> int | None:
+    """Return the 1-based line number of the first line containing *selection_text*.
+
+    Returns ``None`` when:
+    - *selection_text* is empty
+    - the file cannot be read
+    - no line contains the text
+    """
+    if not selection_text:
+        return None
+    try:
+        lines = source_path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return None
+    for i, line in enumerate(lines, start=1):
+        if selection_text in line:
+            return i
+    return None