Add docs, community md etc (#25)

fixes #4

Author: phoeenniixx

CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+Generated from merged pull requests with `build_tools/changelog.py`; see that file's
+docstring for how classification works.

CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing
+
+PyQit is `0.1.0b1`, unstable, and mostly one maintainer plus dependabot. Issues and PRs
+are welcome, and this doubles as a note-to-self for keeping things consistent.
+
+## Setup
+
+```bash
+git clone https://github.com/phoeenniixx/pyqit.git
+cd pyqit
+pip install -e ".[dev]"              # base + test tooling
+pip install -e ".[dev,all_extras]"   # + torch, lightning, matplotlib, rich
+pre-commit install
+```
+
+`all_extras` is what CI runs against, so a PR touching torch/lightning/matplotlib/rich
+needs it locally to actually exercise that code. Anything new in that area also needs to
+degrade gracefully with only `[dev]` installed, since CI runs both.
+
+## Before opening a PR
+
+```bash
+python -m pytest
+pre-commit run --all-files       # ruff, ruff-format, nbQA on notebooks
+```
+
+Run the notebooks if you touched anything they import. `run-notebook-tutorials` runs them
+in CI too, `--inplace`, so the same command regenerates their stored outputs locally
+before you commit.
+
+## Adding an ansatz, embedding, model, or loss
+
+There's no registration step. A class with the right `object_type` tag is picked up by
+`all_objects()` and enrolled in the test suite automatically, as long as it implements
+`get_test_params()`. One catch: skbase's discovery walk skips any module whose name
+starts with `_`, so a class defined there is silently never found. Put it somewhere
+else.
+
+## Soft dependencies
+
+torch, lightning, matplotlib, and rich are optional. Guard any import of them with
+`skbase.utils.dependencies._check_soft_dependencies(..., severity="none")`, not
+`_safe_import`. `_safe_import` falls back to a `MagicMock`, and a missing dependency
+then returns mock objects instead of raising, which fails in stranger ways somewhere
+downstream instead of at the import.
+
+## Labeling PRs
+
+`build_tools/changelog.py` builds the changelog from merged PRs, sorted into Bug fixes,
+Enhancements, Documentation, and Maintenance by GitHub label first, a keyword guess from
+the title second. Add one of `bug`, `enhancement`, `documentation`, `maintenance` when
+you open or merge a PR. An unlabeled PR that also doesn't match a keyword lands in a
+"Needs a label" bucket rather than getting force-fit into one of the four; the fix is to
+label it and rerun the script, not to hand-edit the output.
+
+## Commit messages
+
+This repo squash-merges, so a PR's title becomes its one commit message on `main`. Write
+the title as you want it to read in the changelog and commit history.

build_tools/changelog.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+"""Draft a changelog entry from merged pull requests on GitHub.
+
+    python build_tools/changelog.py
+    python build_tools/changelog.py --since-pr 20
+    python build_tools/changelog.py --since-date 2026-06-01
+
+Needs the GitHub CLI (``gh``), logged in (``gh auth login``). Queries merged
+PRs against the repository's ``main`` branch on GitHub itself, not local git
+state, so the result does not depend on which branch or commit you happen to
+have checked out.
+
+A PR's ``bug`` / ``enhancement`` / ``documentation`` / ``maintenance`` label
+decides its section. Many PRs in this repo carry no label, so an unlabeled PR
+falls back to a keyword match on its title. A PR that matches no label and no
+keyword lands in "Needs a label" rather than a guessed section, so labeling
+it and re-running is the fix, not moving it by hand.
+
+Nothing is written to CHANGELOG.md automatically. Paste the output in
+yourself, replacing the whole "## Unreleased" section each time -- it is
+meant to be regenerated in full, not appended to. Until you rename that
+heading to a real version and start a fresh "## Unreleased" above it,
+nothing counts as released, so a plain re-run always shows every merged PR
+again. Renaming it to a version heading is what makes "--since-pr" (or the
+auto-detected default) start narrowing later runs.
+"""
+
+import argparse
+import json
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import sys
+
+SECTIONS = {
+    "bug": "Bug fixes",
+    "enhancement": "Enhancements",
+    "documentation": "Documentation",
+    "maintenance": "Maintenance",
+}
+
+# Not a real GitHub label; where a PR lands when no label and no keyword
+# rule below matched it. Kept separate from SECTIONS so it renders last and
+# is never treated as a labelable category to search for on a PR.
+UNCLASSIFIED = "unclassified"
+UNCLASSIFIED_HEADING = "Needs a label"
+
+# Tried in order against the title, for PRs with no matching label.
+KEYWORD_RULES = [
+    ("bug", re.compile(r"\bfix|bug|hotfix|\bpatch", re.I)),
+    (
+        "documentation",
+        re.compile(r"\bdocs?\b|readme|tutorial|notebook|changelog|contributing", re.I),
+    ),
+    (
+        "maintenance",
+        re.compile(
+            r"\bchore|refactor|cleanup|bump|deps?\b|dependabot|\bci\b|revert"
+            r"|merge branch",
+            re.I,
+        ),
+    ),
+]
+
+CHANGELOG_PATH = Path(__file__).resolve().parent.parent / "CHANGELOG.md"
+
+
+def _run(cmd: list[str]) -> str:
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        sys.exit(f"$ {' '.join(cmd)}\n{result.stderr.strip()}")
+    return result.stdout
+
+
+def _require_gh() -> None:
+    if shutil.which("gh") is None:
+        sys.exit("Needs the GitHub CLI ('gh'). Install it, then 'gh auth login'.")
+    if subprocess.run(["gh", "auth", "status"], capture_output=True).returncode != 0:
+        sys.exit("'gh' is not logged in. Run 'gh auth login' first.")
+
+
+def _default_repo() -> str:
+    """OWNER/REPO, read from the 'origin' remote rather than hardcoded."""
+    url = _run(["git", "remote", "get-url", "origin"]).strip()
+    match = re.search(r"github\.com[:/](?P<repo>[^/]+/[^/]+?)(\.git)?$", url)
+    if not match:
+        sys.exit(f"Could not read a GitHub repo from the 'origin' remote: {url!r}")
+    return match.group("repo")
+
+
+def _last_released_pr() -> int | None:
+    """Highest PR number under the most recent *released* heading.
+
+    "## Unreleased" is not a release: it gets fully regenerated on every run
+    until you rename it to a real version and start a fresh, empty
+    "Unreleased" above it. Counting PRs already listed there as "handled"
+    would mean a plain re-run stops reporting anything the moment you first
+    paste a draft in, which is the wrong direction -- there is nothing to
+    protect against re-showing until something has actually shipped.
+    """
+    if not CHANGELOG_PATH.exists():
+        return None
+    sections = re.split(r"^## (.+)$", CHANGELOG_PATH.read_text(), flags=re.M)
+    for heading, body in zip(sections[1::2], sections[2::2]):
+        if heading.strip().lower() == "unreleased":
+            continue
+        numbers = [int(n) for n in re.findall(r"\[#(\d+)\]", body)]
+        return max(numbers) if numbers else None
+    return None
+
+
+def fetch_merged_prs(repo: str, base: str, limit: int) -> list[dict]:
+    out = _run(
+        [
+            "gh",
+            "pr",
+            "list",
+            "-R",
+            repo,
+            "--base",
+            base,
+            "--state",
+            "merged",
+            "--limit",
+            str(limit),
+            "--json",
+            "number,title,author,labels,mergedAt,url",
+        ]
+    )
+    return json.loads(out)
+
+
+def classify(pr: dict) -> str:
+    labels = {label["name"] for label in pr["labels"]}
+    for key in SECTIONS:
+        if key in labels:
+            return key
+    for key, pattern in KEYWORD_RULES:
+        if pattern.search(pr["title"]):
+            return key
+    return UNCLASSIFIED
+
+
+def render(prs: list[dict], heading: str) -> str:
+    all_sections = {**SECTIONS, UNCLASSIFIED: UNCLASSIFIED_HEADING}
+    buckets: dict[str, list[dict]] = {key: [] for key in all_sections}
+    for pr in prs:
+        buckets[classify(pr)].append(pr)
+
+    lines = [
+        "<!-- Draft, not a source of truth. A PR's label decides its "
+        "section; an unlabeled PR is guessed from its title. Anything "
+        "matching neither ends up in 'Needs a label' -- label it on "
+        "GitHub and re-run rather than moving it here by hand. -->",
+        "",
+        f"## {heading}",
+        "",
+    ]
+    for key, section_heading in all_sections.items():
+        entries = buckets[key]
+        if not entries:
+            continue
+        lines.append(f"### {section_heading}")
+        lines.append("")
+        for pr in entries:
+            login = pr["author"].get("login", "unknown")
+            lines.append(
+                f"- {pr['title']} ([#{pr['number']}]({pr['url']})) "
+                f"by [@{login}](https://github.com/{login})"
+            )
+        lines.append("")
+
+    contributors = sorted(
+        {pr["author"]["login"] for pr in prs if not pr["author"].get("is_bot", False)},
+        key=str.lower,
+    )
+    if contributors:
+        lines.append("### Contributors")
+        lines.append("")
+        lines.append("Thanks to the following people for this release:")
+        lines.append("")
+        lines.append(
+            ", ".join(
+                f"[@{login}](https://github.com/{login})" for login in contributors
+            )
+        )
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parser.add_argument(
+        "--repo", default=None, help="OWNER/REPO. Default: read from 'origin'."
+    )
+    parser.add_argument(
+        "--base", default="main", help="Base branch merged PRs target. Default: main."
+    )
+    parser.add_argument(
+        "--since-pr", type=int, default=None, help="Only PRs numbered above this."
+    )
+    parser.add_argument(
+        "--since-date", default=None, help="Only PRs merged after this (YYYY-MM-DD)."
+    )
+    parser.add_argument(
+        "--limit", type=int, default=300, help="Max merged PRs to fetch. Default 300."
+    )
+    parser.add_argument(
+        "--title", default="Unreleased", help="Section heading. Default: Unreleased."
+    )
+    parser.add_argument("--output", default=None, help="Also write the markdown here.")
+    args = parser.parse_args()
+
+    _require_gh()
+    repo = args.repo or _default_repo()
+
+    since_pr = args.since_pr
+    if since_pr is None and args.since_date is None:
+        since_pr = _last_released_pr()
+
+    prs = fetch_merged_prs(repo, args.base, args.limit)
+
+    if since_pr is not None:
+        prs = [pr for pr in prs if pr["number"] > since_pr]
+    if args.since_date is not None:
+        prs = [pr for pr in prs if pr["mergedAt"][:10] > args.since_date]
+
+    if not prs:
+        sys.exit("No merged PRs in range. Nothing to report.")
+
+    prs.sort(key=lambda pr: pr["number"], reverse=True)
+
+    markdown = render(prs, args.title)
+    print(markdown)
+
+    if args.output:
+        Path(args.output).write_text(markdown)
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -82,8 +82,7 @@ github-actions = ["pytest-github-actions-annotate-failures"]
 
 [tool.setuptools.packages.find]
 exclude = ["build_tools"]
-where = ["."]
-include = ["pyqit*"]
+include = ["pyqit", "pyqit*"]
 
 [build-system]
 build-backend = "setuptools.build_meta"
@@ -133,6 +132,7 @@ extend-ignore = [
 
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401"]
+"build_tools/changelog.py" = ["S603", "S607"]
 
 [tool.ruff.lint.isort]
 known-first-party = ["pyqit"]

pyqit/ansatzes/base.py

@@ -4,6 +4,8 @@
 
 
 class BaseAnsatz(_PyQitObject):
+    """Base class for a parameterized quantum circuit block."""
+
     _tags = {
         "object_type": "ansatz",
         "ansatz_type": None,

pyqit/core/adapters/lightning.py

@@ -11,14 +11,20 @@
     )
 
     class Callback:
+        """Stub used when lightning/torch is missing; raises on construction."""
+
         def __init__(self, *args, **kwargs):
             raise ImportError(_MESSAGE)
 
     class LightningModule:
+        """Stub used when lightning/torch is missing; raises on construction."""
+
         def __init__(self, *args, **kwargs):
             raise ImportError(_MESSAGE)
 
     class LightningDataModule:
+        """Stub used when lightning/torch is missing; raises on construction."""
+
         def __init__(self, *args, **kwargs):
             raise ImportError(_MESSAGE)
 

pyqit/core/callbacks/base.py

@@ -60,4 +60,5 @@ def on_fit_end(self, state: LoopState) -> None:
 
     @classmethod
     def get_test_params(cls):
+        """List constructor kwargs used to parametrize this class in the test suite."""
         return [{}]

pyqit/core/callbacks/checkpoint.py

@@ -200,4 +200,5 @@ def _write(self, model, weights: dict, stem: str) -> str:
 
     @classmethod
     def get_test_params(cls):
+        """List constructor kwargs used to parametrize this class in the test suite."""
         return [{}, {"save_best": False, "save_last": True}]

pyqit/core/callbacks/history.py

@@ -39,6 +39,7 @@ def on_epoch_end(self, state: LoopState) -> None:
 
     @classmethod
     def get_test_params(cls):
+        """List constructor kwargs used to parametrize this class in the test suite."""
         from pyqit.core.trainer import TrainingHistory
 
         return [{"history_obj": TrainingHistory()}]