sphinx-java-autodoc 0.2.0__tar.gz

sphinx_java_autodoc-0.2.0/.gitignore

@@ -0,0 +1,18 @@
+.venv*/
+__pycache__/
+.pytest_cache/
+*.egg-info/
+build/
+dist/
+docs/_build/
+docs/api/
+examples/**/target/
+examples/**/build/
+examples/**/docs/_build/
+examples/**/docs/api/
+
+
+.java-autodoc-cache/
+.ruff_cache/
+.DS_Store
+examples/**/.gradle/

sphinx_java_autodoc-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,125 @@
+# Development
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and Temurin
+JDK 25. Ensure `java`, `javac`, and `javadoc` are on `PATH`.
+
+```sh
+uv sync --locked
+uv run --locked pre-commit install
+uv run --locked pre-commit run --all-files
+uv run --locked pytest -q
+uv run --locked --group showcase python showcase/build.py
+uv run --locked sphinx-build -W --keep-going -n docs docs/_build/html
+uv build
+uv run --locked twine check --strict dist/*
+```
+
+The docs link into the Apache Commons Lang showcase, so build it first:
+`showcase/build.py` fetches the pinned commit, builds its site under
+`build/showcase/commons-lang/html/<theme>/` in Furo, Read the Docs, Alabaster
+and Lumina (the `showcase` dependency group), and fails when a theme's warning category
+exceeds the shared baseline in `showcase/commons-lang/showcase.json`. After a change that removes
+warnings, record the new counts with `--update-baseline`; an increase needs a
+deliberate baseline update in the same change.
+
+`pre-commit install` sets up the commit and commit-message hooks; CI runs the same
+hooks in the Lint job. They cover Ruff lint and formatting, google-java-format for
+the doclet (the formatter Spotless uses for Java, pinned by checksum),
+`javac -Xlint:all -Werror`, actionlint, zizmor, typos, `pyproject.toml`
+validation, RST pitfalls, `uv.lock` freshness and basic file hygiene. Commit
+messages must use conventional prefixes such as `feat:`, `fix:` or `docs:`, and
+direct commits to `main` are rejected. Hooks with `--fix`/`--autofix` rewrite
+files; review and stage their changes. Python tools run through `uv run --locked`,
+so their versions come from `uv.lock`.
+
+Update dependencies with `uv lock --upgrade`, and commit `uv.lock` with changes to
+`pyproject.toml`. CI uses `--locked` so a stale lockfile fails. Dependabot opens
+weekly updates, after a seven-day cooldown, for Python packages, pinned GitHub
+Actions and pre-commit hook revisions. To update hooks by hand, run
+`uv run --locked pre-commit autoupdate --freeze`.
+
+For the browser checks:
+
+```sh
+uv sync --locked --extra test --group showcase
+uv run --locked --extra test --group showcase playwright install chromium
+for theme in alabaster classic furo sphinx_rtd_theme lumina; do
+  output=$theme; [ "$theme" = alabaster ] && output=html
+  uv run --locked --extra test --group showcase sphinx-build -W --keep-going -n \
+    -D "html_theme=$theme" examples/standalone/docs "examples/standalone/docs/_build/$output"
+done
+uv run --locked --extra test --group showcase python tests/visual_check.py
+```
+
+Browser checks use the small site in `examples/standalone/docs`, which renders the
+standalone fixture with every documented feature. They cover
+desktop/mobile layouts, Java API structure and navigation in Alabaster, Classic,
+Furo, Read the Docs and Lumina, including Sphinx's search page, and fail on
+uncaught page errors. CI retains screenshots and a JSON report, including on failures.
+API pages must not be wider than the theme's own layout, measured on the index and
+on `reference.rst`, a page of native Sphinx objects with the same fields. Classic
+keeps a minimum page width, and some themes overflow on phones for native objects.
+
+The opt-in `uv run --locked python tests/build_tools_check.py` check needs Maven
+and Gradle on PATH (or explicit `--maven`/`--gradle` executable paths). It runs the
+consumer builds and verifies strict extraction and JDK-free publication. Build
+tools resolve their declared dependencies explicitly. For real-project timing,
+use `uv run --locked python tests/benchmark.py /prepared/source/root`; see
+`docs/performance.rst` for the measured workload and limitations.
+
+The required `All checks` status covers lint, compiler warnings, the test matrix,
+source/wheel packaging, the Commons Lang showcase baseline, strict docs, browser
+checks, Maven/Gradle consumers, and dependency auditing.
+Package checks install the wheel built from the source archive and run the real
+integration suite against that installation. Weekly CI also detects newly
+reported vulnerabilities. The application remains an initial release; passing CI
+does not extend the compatibility promises in `docs/compatibility.rst`;
+update that page when a new environment has actually passed.
+
+# Releases
+
+One-time PyPI setup must be completed by the PyPI account owner. Register a
+[pending trusted publisher](https://pypi.org/manage/account/publishing/) with:
+
+| Field | Value |
+| --- | --- |
+| PyPI project name | `sphinx-java-autodoc` |
+| GitHub owner | `r4sky0` |
+| Repository | `sphinx-java-autodoc` |
+| Workflow filename | `release.yml` |
+| Environment | `pypi` |
+
+The GitHub repository and the Python distribution share the name
+`sphinx-java-autodoc`. If the project already exists on PyPI, add the publisher in that project's Publishing settings instead. No PyPI
+API token or repository deploy key is needed. See the
+[PyPI trusted publisher documentation](https://docs.pypi.org/trusted-publishers/adding-a-publisher/).
+
+Releases are prepared by [Release Please](https://github.com/googleapis/release-please).
+On every push to `main`, it opens or updates a release PR from the conventional
+commits since the last release. That PR bumps `[project].version` in
+`pyproject.toml`, `VERSION` in `src/sphinx_java_autodoc/extractor.py` and the
+project entry in `uv.lock`, and updates `CHANGELOG.md`. Before 1.0, `feat:` and
+breaking changes bump the minor version and everything else the patch version.
+Add a `Release-As: 0.3.0` footer to a commit to choose the version explicitly.
+
+To release, review and merge the release PR once `All checks` passes. Release
+Please then tags the merge commit, drafts a GitHub release with the changelog and
+dispatches the Release workflow for that tag. PRs and tags created with the
+default `GITHUB_TOKEN` don't trigger workflows by themselves, so Release Please
+also dispatches CI for its release PR.
+
+The Release workflow rejects branches, tags that disagree with either version,
+and commits outside `main`. It reruns CI on the tagged commit, publishes the
+tested wheel and sdist using PyPI OIDC with attestations, then attaches them to
+the draft release and publishes it. Published versions are immutable; fix a bad
+release with a new version. A tag pushed by hand, for example `v0.1.0`, still
+runs the same workflow and creates a release with generated notes.
+
+To retry a failed release, rerun failed jobs in GitHub Actions. If publishing has
+not succeeded, you can also dispatch Release manually and select the existing
+tag. Dispatching against a branch deliberately fails validation.
+
+GitHub Pages uses the built documentation artifact from a successful `main` push.
+Each open same-repository PR is also published at `pr-preview/pr-<number>/`
+after its CI passes, with a link commented on the PR; fork PRs are not deployed. GitHub environments restrict
+Pages to `main` and PyPI publishing to `v*` tags.

sphinx_java_autodoc-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sphinx-java-autodoc contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sphinx_java_autodoc-0.2.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.5
+Name: sphinx-java-autodoc
+Version: 0.2.0
+Summary: Compiler-backed Java API documentation in native Sphinx nodes
+Project-URL: Documentation, https://r4sky0.github.io/sphinx-java-autodoc/
+Project-URL: Repository, https://github.com/r4sky0/sphinx-java-autodoc
+Project-URL: Issues, https://github.com/r4sky0/sphinx-java-autodoc/issues
+Project-URL: Changelog, https://github.com/r4sky0/sphinx-java-autodoc/releases
+Author: Ralph Offinger
+License-Expression: MIT
+License-File: LICENSE
+Keywords: autodoc,documentation,java,javadoc,sphinx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Java
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation :: Sphinx
+Requires-Python: >=3.12
+Requires-Dist: sphinx<9.2,>=9.1
+Provides-Extra: test
+Requires-Dist: build>=1; extra == 'test'
+Requires-Dist: playwright>=1.50; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# sphinx-java-autodoc
+
+[![CI](https://github.com/r4sky0/sphinx-java-autodoc/actions/workflows/ci.yml/badge.svg)](https://github.com/r4sky0/sphinx-java-autodoc/actions/workflows/ci.yml)
+[Documentation](https://r4sky0.github.io/sphinx-java-autodoc/)
+
+Publish your Java library's guides and API reference in one searchable Sphinx
+site. Keep API contracts in Java sources and Javadoc; write guides that help
+your users choose an API and complete a task.
+
+`sphinx-java-autodoc` reads Java sources and Javadoc comments with the JDK compiler
+APIs and renders them as native Sphinx content:
+
+- Generated, searchable pages for classes, interfaces, enums, records, annotation
+  types and nested types.
+- Signatures, overloads, Javadoc links and inherited method documentation.
+- Class excerpts in handwritten guides, and links between projects through intersphinx.
+- Pages that refresh when sources change, with content-based extraction caching.
+
+Extraction never executes application classes or annotation processors, and never
+downloads Java dependencies. See the [Apache Commons Lang example](https://r4sky0.github.io/sphinx-java-autodoc/showcase/commons-lang/furo/)
+for what the output looks like.
+
+## Requirements
+
+Python 3.12+, Sphinx 9.1.x, and **JDK 25 for extraction**. Your library can keep
+targeting Java 17 or 21. See [compatibility and limits](https://r4sky0.github.io/sphinx-java-autodoc/compatibility.html)
+for the tested versions.
+
+## Quick start
+
+```sh
+uv add "sphinx-java-autodoc @ git+https://github.com/r4sky0/sphinx-java-autodoc.git"
+```
+
+In `docs/conf.py`:
+
+```python
+extensions = ["sphinx_java_autodoc"]
+java_sources = ["../src/main/java"]
+java_release = "17"
+java_generate = "api"
+java_visibility = "public"
+```
+
+Add `api/index` to the toctree in `docs/index.rst`, then build:
+
+```sh
+uv run sphinx-build -W --keep-going -n docs docs/_build/html
+```
+
+[Publish your first API pages](https://r4sky0.github.io/sphinx-java-autodoc/getting-started.html) walks through these steps.
+Then continue with:
+
+- [Write a guide your users can follow](https://r4sky0.github.io/sphinx-java-autodoc/guide.html)
+- [Build with dependencies and CI](https://r4sky0.github.io/sphinx-java-autodoc/build-integration.html): Maven/Gradle
+  classpaths, pre-extracted models and publishing to GitHub Pages
+- [Configuration and reference](https://r4sky0.github.io/sphinx-java-autodoc/usage.html) and [supported Javadoc](https://r4sky0.github.io/sphinx-java-autodoc/javadoc-support.html)
+- [Troubleshooting](https://r4sky0.github.io/sphinx-java-autodoc/troubleshooting.html)
+- [How it works](https://r4sky0.github.io/sphinx-java-autodoc/design.html) and the [architecture decision](docs/adr/0001-jdk-doclet-xml-sphinx-domain.md)
+
+## Development
+
+From a clone of this repository:
+
+```sh
+uv sync --locked
+uv run --locked pre-commit install
+uv run --locked pre-commit run --all-files
+uv run --locked pytest
+uv run --locked --group showcase python showcase/build.py
+uv run --locked sphinx-build -W --keep-going -n docs docs/_build/html
+```
+
+Development and releases are documented in [CONTRIBUTING.md](CONTRIBUTING.md).
+CI covers lint, compiler warnings, integration tests, built distributions,
+dependency vulnerabilities, six HTML themes, the text builder, and Chromium
+browser interactions.
+
+[MIT licensed](LICENSE).

sphinx_java_autodoc-0.2.0/README.md

@@ -0,0 +1,79 @@
+# sphinx-java-autodoc
+
+[![CI](https://github.com/r4sky0/sphinx-java-autodoc/actions/workflows/ci.yml/badge.svg)](https://github.com/r4sky0/sphinx-java-autodoc/actions/workflows/ci.yml)
+[Documentation](https://r4sky0.github.io/sphinx-java-autodoc/)
+
+Publish your Java library's guides and API reference in one searchable Sphinx
+site. Keep API contracts in Java sources and Javadoc; write guides that help
+your users choose an API and complete a task.
+
+`sphinx-java-autodoc` reads Java sources and Javadoc comments with the JDK compiler
+APIs and renders them as native Sphinx content:
+
+- Generated, searchable pages for classes, interfaces, enums, records, annotation
+  types and nested types.
+- Signatures, overloads, Javadoc links and inherited method documentation.
+- Class excerpts in handwritten guides, and links between projects through intersphinx.
+- Pages that refresh when sources change, with content-based extraction caching.
+
+Extraction never executes application classes or annotation processors, and never
+downloads Java dependencies. See the [Apache Commons Lang example](https://r4sky0.github.io/sphinx-java-autodoc/showcase/commons-lang/furo/)
+for what the output looks like.
+
+## Requirements
+
+Python 3.12+, Sphinx 9.1.x, and **JDK 25 for extraction**. Your library can keep
+targeting Java 17 or 21. See [compatibility and limits](https://r4sky0.github.io/sphinx-java-autodoc/compatibility.html)
+for the tested versions.
+
+## Quick start
+
+```sh
+uv add "sphinx-java-autodoc @ git+https://github.com/r4sky0/sphinx-java-autodoc.git"
+```
+
+In `docs/conf.py`:
+
+```python
+extensions = ["sphinx_java_autodoc"]
+java_sources = ["../src/main/java"]
+java_release = "17"
+java_generate = "api"
+java_visibility = "public"
+```
+
+Add `api/index` to the toctree in `docs/index.rst`, then build:
+
+```sh
+uv run sphinx-build -W --keep-going -n docs docs/_build/html
+```
+
+[Publish your first API pages](https://r4sky0.github.io/sphinx-java-autodoc/getting-started.html) walks through these steps.
+Then continue with:
+
+- [Write a guide your users can follow](https://r4sky0.github.io/sphinx-java-autodoc/guide.html)
+- [Build with dependencies and CI](https://r4sky0.github.io/sphinx-java-autodoc/build-integration.html): Maven/Gradle
+  classpaths, pre-extracted models and publishing to GitHub Pages
+- [Configuration and reference](https://r4sky0.github.io/sphinx-java-autodoc/usage.html) and [supported Javadoc](https://r4sky0.github.io/sphinx-java-autodoc/javadoc-support.html)
+- [Troubleshooting](https://r4sky0.github.io/sphinx-java-autodoc/troubleshooting.html)
+- [How it works](https://r4sky0.github.io/sphinx-java-autodoc/design.html) and the [architecture decision](docs/adr/0001-jdk-doclet-xml-sphinx-domain.md)
+
+## Development
+
+From a clone of this repository:
+
+```sh
+uv sync --locked
+uv run --locked pre-commit install
+uv run --locked pre-commit run --all-files
+uv run --locked pytest
+uv run --locked --group showcase python showcase/build.py
+uv run --locked sphinx-build -W --keep-going -n docs docs/_build/html
+```
+
+Development and releases are documented in [CONTRIBUTING.md](CONTRIBUTING.md).
+CI covers lint, compiler warnings, integration tests, built distributions,
+dependency vulnerabilities, six HTML themes, the text builder, and Chromium
+browser interactions.
+
+[MIT licensed](LICENSE).

sphinx_java_autodoc-0.2.0/SECURITY.md

@@ -0,0 +1,10 @@
+# Security
+
+Security fixes target the latest published version. Until the first publication,
+use the latest `main` commit and review the known limits in
+`docs/compatibility.rst`.
+
+Report vulnerabilities privately through
+[GitHub security reporting](https://github.com/r4sky0/sphinx-java-autodoc/security/advisories/new).
+Include a minimal reproducer, the affected version, and Python/JDK versions.
+Please keep exploit details out of public issues while a fix is being prepared.

sphinx_java_autodoc-0.2.0/docs/adr/0001-jdk-doclet-xml-sphinx-domain.md

@@ -0,0 +1,71 @@
+# ADR 001: JDK doclet, versioned XML, native Sphinx domain
+
+Accepted 2026-10-10 after a doclet prototype; research date 2026-10-10.
+
+Use the supported `jdk.javadoc.doclet` and compiler model APIs to inspect source
+without loading application classes. The compiler resolves signatures, imports,
+overloads, type erasure, and overrides. Comment inheritance is a separate doclet
+responsibility: a doclet receives an unexpanded `INHERIT_DOC` node and can locate
+the overridden generic method using `Elements.overrides`. There is no supported
+call that returns the standard doclet's fully inherited documentation, and ancestor
+comments are only available when the ancestor's source is supplied.
+
+Use XML schema version 1 across the process boundary. The JDK includes DOM/XML
+serialization and Python includes ElementTree. JSON is equally capable but would
+require a Java JSON library or our own JSON serializer. XML preserves ordered
+comment tokens without re-parsing Javadoc strings; semantic reference targets
+travel alongside their presentation labels. Neither format supplies semantics
+on its own. No upstream implementation is copied.
+
+Render native docutils paragraphs, lists, literal blocks, Sphinx descriptions,
+and pending cross-references. A `java` domain owns inventories and resolution.
+Only page skeletons (titles, toctrees, directives) use generated reStructuredText;
+source comments are never interpreted as reStructuredText or embedded raw HTML.
+
+Run extraction once before Sphinx reads documents. Hash source and dependency
+contents, options, JDK identity and extractor code. Cache complete immutable XML
+snapshots and atomically replace files. A changed model invalidates consuming
+documents even if filesystem timestamps do not change. This intentionally uses
+whole-project extraction rather than fragile per-file semantic invalidation.
+
+The initial runtime baseline is JDK 25. Traditional Javadoc and the JDK 25
+automatic inheritance search are supported; snippet expansion and Markdown
+comments initially produced diagnostics (plain inline snippets were added later). This avoids promising old-JDK
+compatibility without running old JDKs. See the validation report for tested
+Python/Sphinx versions and exact boundaries.
+
+Tradeoffs: a JDK and a resolvable compile classpath are required; we own a compact
+doc-comment-to-node mapping and inheritance implementation.
+
+## Alternatives considered
+
+Assessed from official documentation and source inspection; only the selected
+backend was prototyped. Other tools' runtime behavior and speed were not measured.
+
+- **[Manticore XMLDoclet](https://github.com/manticore-projects/xml-doclet) +
+  [sphinx-javadoc-xml](https://github.com/manticore-projects/sphinx-javadoc-xml):**
+  rich declaration metadata, but `Parser.getJavaDoc` stringifies comment bodies, the
+  schema has no resolved inline-link targets or record components, and the renderer
+  removes `inheritDoc` and registers directives without a Java domain.
+- **Doxygen with [Breathe](https://github.com/breathe-doc/breathe) or
+  [Doxysphinx](https://github.com/boschglobal/doxysphinx):** Doxygen's Java dialect
+  is not the JDK documentation model, Breathe's domains target C/C++, and Doxysphinx
+  wraps Doxygen HTML in raw directives instead of native Java objects.
+- **[JavaParser](https://github.com/javaparser/javaparser),
+  [Eclipse JDT](https://github.com/eclipse-jdt/eclipse.jdt.core),
+  [tree-sitter-java](https://github.com/tree-sitter/tree-sitter-java):** a second
+  parser to configure and maintain, with our own type resolution (or none, for
+  tree-sitter) and still our own inheritance and rendering.
+- **Reflection or bytecode:** no source comments, and loading classes can run
+  static initializers.
+- **Parsing generated Javadoc HTML:** presentation markup is an unstable
+  interchange format and semantic identities would have to be reconstructed.
+
+From the Sphinx side, [sphinx-autoapi](https://github.com/readthedocs/sphinx-autoapi)
+informed page generation at `builder-inited`,
+[sphinx-autodoc2](https://github.com/sphinx-extensions2/sphinx-autodoc2) the
+separation of analysis and rendering with content-hash caching, and
+[sphinx-js](https://github.com/pyodide/sphinx-js) the structured process boundary.
+The archived [javasphinx](https://github.com/bronto/javasphinx) issues (inheritDoc,
+default methods, encoding, parallel builds) motivated compiler-backed parsing,
+explicit diagnostics, content fingerprints and domain merge tests. No code was copied.

sphinx_java_autodoc-0.2.0/docs/agents/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_

sphinx_java_autodoc-0.2.0/docs/agents/issue-tracker.md

@@ -0,0 +1,45 @@
+# Issue tracker: GitHub
+
+Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v`; `gh` does this automatically when run inside a clone.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+
+- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
+- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments` then keep only `authorAssociation` of `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`).
+- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either: resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitHub's **native issue dependencies**, the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only, the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Claim**: `gh issue edit <n> --add-assignee @me`, the session's first write.
+- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

sphinx_java_autodoc-0.2.0/docs/alternatives.rst

@@ -0,0 +1,108 @@
+Choosing a tool
+===============
+
+Several tools put Java API documentation into Sphinx, and a plain Javadoc site is
+always an option. This page shows how they compare so you can pick the one that
+fits your project, even if that isn't this extension.
+
+The other tools were assessed in October 2026 by reading their documentation and
+source code, not by running them. If something here is out of date, please
+`open an issue <https://github.com/r4sky0/sphinx-java-autodoc/issues>`_.
+
+At a glance
+-----------
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :widths: 20 20 20 20 20
+
+   * -
+     - sphinx-java-autodoc
+     - `sphinx-javadoc-xml <https://github.com/manticore-projects/sphinx-javadoc-xml>`_
+     - `javasphinx <https://github.com/bronto/javasphinx>`_
+     - Doxygen + `Breathe <https://github.com/breathe-doc/breathe>`_ / `Exhale <https://github.com/svenevs/exhale>`_
+   * - Maintained
+     - Yes
+     - Yes
+     - No, archived in 2019
+     - Yes
+   * - Reads your Java with
+     - The JDK's own ``javadoc`` tool
+     - A third-party XML doclet you run in Maven or Gradle
+     - ``javalang``, a Python parser for Java 8 syntax
+     - Doxygen's own parser
+   * - Modern Java (records, sealed types, modules)
+     - Whatever JDK 25 accepts
+     - Limited to what the XML doclet records; no record components
+     - No
+     - Partial
+   * - ``{@link}`` in comments
+     - Clickable link to the resolved target
+     - Shown as code, not linked
+     - Linked by name, resolved by Sphinx
+     - Linked by Doxygen's resolver
+   * - ``{@inheritDoc}``
+     - Resolved; a warning if it can't be
+     - Removed
+     - Not supported
+     - Handled by Doxygen
+   * - Comment rendering
+     - Native Sphinx nodes
+     - Converted to reStructuredText text
+     - HTML converted to reStructuredText text
+     - Breathe: native nodes; Doxysphinx: Doxygen HTML
+   * - Java roles for your own pages (``:java:type:``)
+     - Yes
+     - No
+     - Yes
+     - No, only the C++ domain
+   * - Intersphinx inventory for other sites
+     - Yes
+     - No
+     - Yes
+     - C++ objects only
+   * - Look
+     - Follows your Sphinx theme
+     - Own Javadoc-style CSS; loads web fonts from a CDN by default
+     - Follows your Sphinx theme
+     - Follows your Sphinx theme
+   * - API pages
+     - Generated during the Sphinx build
+     - One directive per API, package or class in your pages
+     - Generated by a separate command; you commit the files
+     - One directive per class, or generated by Exhale
+   * - Needs at docs build time
+     - JDK 25, or no JDK with a :doc:`pre-extracted model <build-integration>`
+     - Only the XML file
+     - Only Python
+     - The ``doxygen`` program
+
+When to choose which
+--------------------
+
+**sphinx-java-autodoc** fits when you want guides and the API reference in one
+Sphinx site, with links that resolve and inherited documentation that stays in
+place. You need JDK 25 to extract, although your library can target Java 17 or
+21. See :doc:`compatibility` for tested versions and known limits.
+
+**sphinx-javadoc-xml** fits when you already produce XML doclet output in your
+build and want a page that looks like classic Javadoc, and missing ``{@link}``
+targets and inherited comments don't matter for your API.
+
+**javasphinx** isn't a good choice for new projects. Its own README says it should
+be used for historical purposes only, and it can't parse Java newer than 8.
+Several forks exist, but none is released under a new name.
+
+**Doxygen with Breathe or Exhale** fits when one site documents C or C++ next to
+Java and you already run Doxygen. Its Java support is secondary, and Java objects
+appear as C++ ones in Sphinx.
+
+**A separate Javadoc site** fits when your readers expect the standard Javadoc
+layout and your guides can live elsewhere. Sphinx pages can link to it with
+`sphinx.ext.extlinks <https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html>`_.
+`sphinx-javalink <https://github.com/bluekeyes/sphinx-javalink>`_ did this with
+Java-aware roles but hasn't changed since 2016.
+
+The :doc:`design notes <design>` explain why this extension uses the JDK instead
+of these approaches.