mkdocs2confluence 0.13.5__tar.gz → 0.13.7__tar.gz

{mkdocs2confluence-0.13.5/src/mkdocs2confluence.egg-info → mkdocs2confluence-0.13.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.13.5
+Version: 0.13.7
 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

{mkdocs2confluence-0.13.5 → mkdocs2confluence-0.13.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs2confluence"
-version = "0.13.5"
+version = "0.13.7"
 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" }
@@ -68,7 +68,7 @@ build-backend = "setuptools.build_meta"
 where = ["src"]
 
 [tool.setuptools.package-data]
-"mkdocs_to_confluence" = ["skills/**/*.md"]
+"mkdocs_to_confluence" = ["skills/**/*.md", "skills/**/*.py"]
 
 [tool.ruff]
 line-length = 120

{mkdocs2confluence-0.13.5 → mkdocs2confluence-0.13.7/src/mkdocs2confluence.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs2confluence
-Version: 0.13.5
+Version: 0.13.7
 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

{mkdocs2confluence-0.13.5 → mkdocs2confluence-0.13.7}/src/mkdocs2confluence.egg-info/SOURCES.txt

@@ -48,6 +48,7 @@ src/mkdocs_to_confluence/publisher/models.py
 src/mkdocs_to_confluence/publisher/pipeline.py
 src/mkdocs_to_confluence/publisher/planner.py
 src/mkdocs_to_confluence/skills/mkdocs-changelog/SKILL.md
+src/mkdocs_to_confluence/skills/mkdocs-changelog/scripts/changelog_data.py
 src/mkdocs_to_confluence/sync/__init__.py
 src/mkdocs_to_confluence/sync/anchoring.py
 src/mkdocs_to_confluence/sync/command.py

{mkdocs2confluence-0.13.5 → mkdocs2confluence-0.13.7}/src/mkdocs_to_confluence/skill_installer.py

@@ -14,6 +14,21 @@ def _read_skill() -> str:
     return files("mkdocs_to_confluence").joinpath(f"skills/{_SKILL_NAME}/SKILL.md").read_text(encoding="utf-8")
 
 
+def _read_script() -> str:
+    from importlib.resources import files
+    return files("mkdocs_to_confluence").joinpath(
+        f"skills/{_SKILL_NAME}/scripts/changelog_data.py"
+    ).read_text(encoding="utf-8")
+
+
+def _install_script(project_dir: Path) -> Path:
+    """Write changelog_data.py to .mk2conf/scripts/ and return its path."""
+    dest = project_dir / ".mk2conf" / "scripts" / "changelog_data.py"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(_read_script(), encoding="utf-8")
+    return dest
+
+
 def _strip_front_matter(content: str) -> str:
     return _FRONT_MATTER_RE.sub("", content).lstrip("\n")
 
@@ -38,6 +53,10 @@ def install_skill(
     content_full = _read_skill()
     content_body = _strip_front_matter(content_full)
 
+    # Always install the data script to a fixed project-local path so every
+    # AI tool's skill file can reference it unconditionally.
+    _install_script(project_dir)
+
     installed: list[tuple[str, Path]] = []
     explicit = tool is not None
 

mkdocs2confluence-0.13.7/src/mkdocs_to_confluence/skills/mkdocs-changelog/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: mkdocs-changelog
+description: Analyse doc changes since the last CHANGELOG.md update and draft a major-change entry if the changes qualify.
+version: "1.3.0"
+tags: [documentation, git, changelog, mkdocs, confluence]
+specificity: context-specific
+tool_agnostic: true
+authors: [Anders Hybertz]
+tested_on: []
+---
+
+# MkDocs Changelog Entry
+
+Analyse git changes to the docs directory since the last `CHANGELOG.md` commit. If any changes qualify as **MAJOR**, draft a dated changelog entry in the collapsible format and prepend it to `CHANGELOG.md`. If not, explain why and exit without modifying any file.
+
+## When to Use
+
+- After making one or more documentation changes and before running `mk2conf publish`
+- Any point in the writing flow when you want to assess whether a "What's New" entry is warranted
+
+## Steps
+
+1. **Extract git data** — run the bundled data script to get structured, deterministic input:
+
+   Normal update (since last CHANGELOG.md commit):
+   ```
+   python .mk2conf/scripts/changelog_data.py --docs-dir <docs_dir>
+   ```
+
+   Initial changelog (from a specific date):
+   ```
+   python .mk2conf/scripts/changelog_data.py --docs-dir <docs_dir> --since YYYY-MM-DD
+   ```
+
+   The script prints a JSON object to stdout. Use this as your sole source of truth for
+   commits, changed files, and contributors. Do not run git commands yourself.
+
+   If the script is missing, tell the user to run `mk2conf install-skill` first.
+
+   When `--since` is used, the JSON will contain `"mode": "since_date"`. Use this to
+   trigger the initial changelog flow described below.
+
+2. **Read the existing changelog** — read `<docs_dir>/CHANGELOG.md` for context on what
+   was previously recorded.
+
+3. **Decide: is this MAJOR?**
+
+   **MAJOR criteria — any one of these qualifies:**
+   - A new top-level documentation area or section added (a new folder or nav section that didn't exist before)
+   - A significant area deleted or substantially restructured (not just moved or renamed)
+   - A fundamental definition, concept, or policy changed in a way that affects how readers understand the subject
+
+   **NOT major — do not draft an entry for:**
+   - Typo fixes, grammar corrections, spelling
+   - Formatting, diagram adjustments, image swaps
+   - Small additions (a paragraph, a note, a clarification) that do not change the substance
+   - Rewordings that preserve the original meaning
+   - Internal restructuring with no reader-facing impact
+
+4. **If NOT MAJOR** — report what was found, explain in one sentence why it did not qualify,
+   and stop. Do not modify any file.
+
+5. **If MAJOR** — draft an entry using the collapsible format below and prepend it to
+   `CHANGELOG.md`. The previous latest entry (if any) must be converted from `???+` to `???`
+   so only the new entry is expanded by default.
+
+## Entry format
+
+The latest entry uses `???+` (expanded by default on Material, always visible on Confluence).
+All older entries use `???` (collapsed, showing only the date and title as the trigger).
+
+```markdown
+???+ note "YYYY-MM-DD — Brief title describing the major change"
+
+    ### Added
+    - …
+
+    ### Changed
+    - …
+
+    ### Deprecated
+    - …
+
+    ### Removed
+    - …
+
+    ### Fixed
+    - …
+
+    ### Security
+    - …
+
+    Contributors: Name One, Name Two
+```
+
+Rules for the entry:
+
+- Date is the `date` field from the script output (`YYYY-MM-DD`)
+- Title is a brief, reader-facing description — not a git commit message
+- No version numbers — dates only
+- **Include only sections that have actual content** — omit any empty section entirely
+- Section meanings: `Added` (new content), `Changed` (updated content), `Deprecated`
+  (content being phased out), `Removed` (deleted content), `Fixed` (corrected errors or
+  misleading information), `Security` (security-related documentation updates)
+- `Contributors:` line — include when the `contributors` array from the script output has
+  **more than one name**. Omit when there is only one contributor.
+- Content inside the admonition block must be indented with **4 spaces**
+- When prepending, convert the previous `???+` opener to `???` first
+
+## CHANGELOG.md structure
+
+If `CHANGELOG.md` does not exist yet, create it with this header before the first entry:
+
+```markdown
+# Changelog
+
+All notable changes to this documentation are recorded here.
+The format is inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+```
+
+## Initial changelog (--since DATE)
+
+When the script is run with `--since` and the JSON contains `"mode": "since_date"`,
+the user wants to bootstrap a CHANGELOG.md from scratch for a given time window.
+
+Different rules apply:
+
+- **Always draft** — the MAJOR threshold does not apply. This is a retrospective
+  summary, not an incremental gate.
+- **Group by theme**, not by individual commit. Synthesise the changed files and
+  commit subjects into meaningful categories.
+- **Date range in the title** — use the `since` value from the JSON as the start
+  and `date` as the end, e.g. `2026-05-01 → 2026-05-27`.
+- **If CHANGELOG.md already exists**, stop and ask the user whether they want to
+  prepend, append, or replace. Do not overwrite silently.
+- **If CHANGELOG.md does not exist**, create it with the standard header and the
+  entry as `???+`.
+
+Example title: `2026-05-01 → 2026-05-27 — Initial documentation release`
+
+## Pitfalls
+
+- **Do not draft an entry for every change.** The changelog is for readers who want to know
+  what fundamentally changed — not a git log. When in doubt, do not draft.
+- **Do not commit.** Always leave the file for the user to review. The user runs `git add`
+  and `git commit` themselves before publishing.
+- **The script is the only source of git data.** Do not interpret commit messages or diffs
+  yourself — the script output is deterministic and already scoped to the docs directory.
+- **4-space indent is required** inside the admonition block. 2-space or tab indent will
+  break both Material rendering and the Confluence compile step.
+
+## Verification
+
+After drafting, show the user the proposed entry in the terminal and remind them to review
+`CHANGELOG.md` before committing and running `mk2conf publish`.

mkdocs2confluence-0.13.7/src/mkdocs_to_confluence/skills/mkdocs-changelog/scripts/changelog_data.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""Extract changelog-relevant git data and print it as JSON.
+
+Usage (run from the project root):
+    python .mk2conf/scripts/changelog_data.py [--docs-dir docs]
+
+Output is a JSON object on stdout. Nothing is written to disk.
+No external dependencies — stdlib only.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from datetime import date
+
+
+def _run(args: list[str]) -> str:
+    """Run a git command and return stripped stdout. Returns '' on error."""
+    try:
+        result = subprocess.run(
+            args,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        return result.stdout.strip()
+    except FileNotFoundError:
+        return ""
+
+
+def _baseline_commit(changelog_path: str) -> str | None:
+    """Return the SHA of the last commit that touched changelog_path, or None."""
+    sha = _run(["git", "log", "--follow", "-1", "--format=%H", "--", changelog_path])
+    return sha or None
+
+
+def _commit_before_date(since_date: str) -> str | None:
+    """Return the SHA of the last commit strictly before since_date (YYYY-MM-DD), or None."""
+    sha = _run([
+        "git", "log", "--format=%H",
+        f"--before={since_date}",
+        "-1",
+    ])
+    return sha or None
+
+
+def _root_commit() -> str:
+    """Return the SHA of the very first commit in the repo."""
+    return _run(["git", "rev-list", "--max-parents=0", "HEAD"])
+
+
+def _commits_since(baseline: str) -> list[dict[str, str]]:
+    """Return commits reachable from HEAD but not from baseline (exclusive)."""
+    sep = "\x1f"  # unit separator — safe delimiter
+    fmt = f"%H{sep}%s{sep}%aN{sep}%as"  # sha, subject, author name, date
+    raw = _run(["git", "log", f"{baseline}..HEAD", f"--format={fmt}"])
+    if not raw:
+        return []
+    commits = []
+    for line in raw.splitlines():
+        parts = line.split(sep)
+        if len(parts) != 4:  # noqa: PLR2004
+            continue
+        sha, subject, author, commit_date = parts
+        commits.append({"sha": sha, "subject": subject, "author": author, "date": commit_date})
+    return commits
+
+
+def _changed_files(baseline: str, docs_dir: str) -> dict[str, list[str]]:
+    """Return files changed in docs_dir since baseline, grouped by status."""
+    raw = _run([
+        "git", "diff", "--name-status", f"{baseline}..HEAD", "--", docs_dir,
+    ])
+    added: list[str] = []
+    modified: list[str] = []
+    deleted: list[str] = []
+    if not raw:
+        return {"added": added, "modified": modified, "deleted": deleted}
+    for line in raw.splitlines():
+        parts = line.split("\t", maxsplit=1)
+        if len(parts) != 2:  # noqa: PLR2004
+            continue
+        status, path = parts[0].strip(), parts[1].strip()
+        if status.startswith("A"):
+            added.append(path)
+        elif status.startswith("D"):
+            deleted.append(path)
+        elif status.startswith("M") or status.startswith("R") or status.startswith("C"):
+            modified.append(path)
+    return {"added": added, "modified": modified, "deleted": deleted}
+
+
+def _contributors(commits: list[dict[str, str]]) -> list[str]:
+    """Return unique contributor names from commits, preserving first-seen order."""
+    seen: set[str] = set()
+    result: list[str] = []
+    for c in commits:
+        name = c["author"]
+        if name and name not in seen:
+            seen.add(name)
+            result.append(name)
+    return result
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Extract git changelog data as JSON.")
+    parser.add_argument(
+        "--docs-dir",
+        default="docs",
+        help="Path to the MkDocs docs directory, relative to project root (default: docs)",
+    )
+    parser.add_argument(
+        "--since",
+        metavar="DATE",
+        default=None,
+        help=(
+            "Use the last commit before DATE (YYYY-MM-DD) as the baseline instead of the "
+            "last commit that touched CHANGELOG.md. Useful for creating an initial changelog."
+        ),
+    )
+    args = parser.parse_args()
+
+    docs_dir: str = args.docs_dir
+    changelog_rel = f"{docs_dir}/CHANGELOG.md"
+
+    # Baseline resolution — --since takes priority
+    if args.since:
+        baseline = _commit_before_date(args.since)
+        if not baseline:
+            print(
+                f"error: no commit found before {args.since}",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        mode = "since_date"
+    else:
+        baseline = _baseline_commit(changelog_rel) or _root_commit()
+        if not baseline:
+            print(
+                "error: could not determine a baseline commit — is this a git repository?",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        mode = "changelog_commit"
+
+    commits = _commits_since(baseline)
+    changes = _changed_files(baseline, docs_dir)
+    contributors = _contributors(commits)
+
+    output = {
+        "date": date.today().isoformat(),
+        "mode": mode,
+        "since": args.since,
+        "baseline_commit": baseline,
+        "commits": commits,
+        "contributors": contributors,
+        "changes": changes,
+        "docs_dir": docs_dir,
+    }
+
+    print(json.dumps(output, indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

{mkdocs2confluence-0.13.5 → mkdocs2confluence-0.13.7}/tests/test_skill_installer.py

@@ -115,6 +115,17 @@ def test_install_skill_explicit_tool_ignores_detection(tmp_path: Path) -> None:
     assert dest.exists()
 
 
+def test_install_skill_copies_script(tmp_path: Path) -> None:
+    """The data script is always installed to .mk2conf/scripts/ regardless of tool."""
+    install_skill(project_dir=tmp_path, tool="claude")
+
+    script = tmp_path / ".mk2conf" / "scripts" / "changelog_data.py"
+    assert script.exists(), ".mk2conf/scripts/changelog_data.py should be created"
+    content = script.read_text(encoding="utf-8")
+    assert "changelog_data" in content
+    assert "import json" in content
+
+
 def test_install_skill_overwrites_existing(tmp_path: Path) -> None:
     (tmp_path / ".claude").mkdir()
     dest = tmp_path / ".claude" / "commands" / "mk2conf-changelog.md"

mkdocs2confluence-0.13.5/src/mkdocs_to_confluence/skills/mkdocs-changelog/SKILL.md

@@ -1,93 +0,0 @@
----
-name: mkdocs-changelog
-description: Analyse doc changes since the last CHANGELOG.md update and draft a major-change entry if the changes qualify.
-version: "1.1.0"
-tags: [documentation, git, changelog, mkdocs, confluence]
-specificity: context-specific
-tool_agnostic: true
-authors: [Anders Hybertz]
-tested_on: []
----
-
-# MkDocs Changelog Entry
-
-Analyse git changes to the docs directory since the last `CHANGELOG.md` commit. If any changes qualify as **MAJOR**, draft a dated changelog entry and prepend it to `CHANGELOG.md`. If not, explain why and exit without modifying any file.
-
-## When to Use
-
-- After making one or more documentation changes and before running `mk2conf publish`
-- Any point in the writing flow when you want to assess whether a "What's New" entry is warranted
-
-## Steps
-
-1. **Find the baseline** — run `git log --follow -1 --format="%H" -- <docs_dir>/CHANGELOG.md` to get the last commit that touched `CHANGELOG.md`. If no commit is found, use the root commit as the baseline.
-
-2. **Collect doc changes** — run `git diff <baseline>..HEAD -- <docs_dir>/` to see everything that changed in the docs directory since that baseline.
-
-3. **Read the existing changelog** — read `<docs_dir>/CHANGELOG.md` for context on what was previously recorded.
-
-4. **Decide: is this MAJOR?**
-
-   **MAJOR criteria — any one of these qualifies:**
-   - A new top-level documentation area or section added (a new folder or nav section that didn't exist before)
-   - A significant area deleted or substantially restructured (not just moved or renamed)
-   - A fundamental definition, concept, or policy changed in a way that affects how readers understand the subject
-
-   **NOT major — do not draft an entry for:**
-   - Typo fixes, grammar corrections, spelling
-   - Formatting, diagram adjustments, image swaps
-   - Small additions (a paragraph, a note, a clarification) that do not change the substance
-   - Rewordings that preserve the original meaning
-   - Internal restructuring with no reader-facing impact
-
-5. **If NOT MAJOR** — report what was found, explain in one sentence why it did not qualify, and stop. Do not modify any file.
-
-6. **If MAJOR** — draft an entry using this format and prepend it to `CHANGELOG.md`:
-
-```markdown
-## YYYY-MM-DD — Brief title describing the major change
-
-### Added
-- …
-
-### Changed
-- …
-
-### Deprecated
-- …
-
-### Removed
-- …
-
-### Fixed
-- …
-
-### Security
-- …
-```
-
-   Rules for the entry:
-   - Date is today's date in `YYYY-MM-DD` format
-   - Title is a brief, reader-facing description (not a git commit message)
-   - No version numbers — dates only
-   - **Include only sections that have actual content** — omit any empty section entirely
-   - Section meanings: `Added` (new content), `Changed` (updated content), `Deprecated` (content being phased out), `Removed` (deleted content), `Fixed` (corrected errors or misleading information), `Security` (security-related documentation updates)
-
-   Prepend the entry above any existing entries in `CHANGELOG.md`. Do not commit — the user reviews, edits if needed, and commits manually.
-
-## Pitfalls
-
-- **Do not draft an entry for every change.** The changelog is for readers who want to know what fundamentally changed, not a git log. When in doubt, do not draft.
-- **Do not commit.** Always leave the file for the user to review. The user runs `git add` and `git commit` themselves before publishing.
-- **If `CHANGELOG.md` does not exist yet**, create it with this header before the first entry:
-
-```markdown
-# Changelog
-
-All notable changes to this documentation are recorded here.
-The format is inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
-```
-
-## Verification
-
-After drafting, show the user the proposed entry in the terminal and remind them to review `CHANGELOG.md` before committing and running `mk2conf publish`.