sphinx-java-autodoc 0.2.1__tar.gz → 0.3.0__tar.gz

{sphinx_java_autodoc-0.2.1 → sphinx_java_autodoc-0.3.0}/.gitignore

@@ -6,6 +6,7 @@ build/
 dist/
 docs/_build/
 docs/api/
+docs/gallery/api/
 examples/**/target/
 examples/**/build/
 examples/**/docs/_build/

sphinx_java_autodoc-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Development
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and Temurin
+JDK 25, with `java`, `javac` and `javadoc` 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/*
+```
+
+Build the showcase before the docs, because the docs link into it.
+`showcase/build.py` fetches the pinned Apache Commons Lang commit, builds it in
+Furo, Read the Docs, Alabaster and Lumina under `build/showcase/commons-lang/html/<theme>/`,
+and fails when a warning category exceeds the baseline in
+`showcase/commons-lang/showcase.json`. Record lower counts with `--update-baseline`;
+an increase needs a deliberate baseline update in the same change.
+
+The pre-commit hooks also run in CI. They cover Ruff, google-java-format for the
+doclet, `javac -Xlint:all -Werror`, actionlint, zizmor, typos, RST checks and
+`uv.lock` freshness. Commit messages need conventional prefixes (`feat:`, `fix:`,
+`docs:`), and direct commits to `main` are rejected. Hooks with `--fix` rewrite
+files; review and stage their changes.
+
+Update dependencies with `uv lock --upgrade` and commit `uv.lock` together with
+`pyproject.toml`. Dependabot opens weekly updates after a seven-day cooldown.
+
+## 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
+```
+
+The checks render `examples/standalone/docs` at desktop and mobile widths in each
+theme, including the search page, and fail on page errors or when API pages are
+wider than the theme's own layout (measured on `reference.rst`).
+
+## Other checks
+
+- `uv run --locked python tests/build_tools_check.py` runs the Maven and Gradle
+  consumer builds. It needs both tools on `PATH`, or `--maven`/`--gradle` paths.
+- `uv run --locked python tests/benchmark.py /prepared/source/root` times a real
+  project; see `docs/performance.rst`.
+
+The required `All checks` status covers all of the above except the benchmark.
+Passing CI does not widen `docs/compatibility.rst`; update that page only when a
+new environment has actually passed.
+
+# Releases
+
+[Release Please](https://github.com/googleapis/release-please) opens a release PR
+from the conventional commits on `main`. The PR bumps the version in
+`pyproject.toml`, `src/sphinx_java_autodoc/extractor.py` and `uv.lock`, and updates
+`CHANGELOG.md`. Before 1.0, `feat:` and breaking changes bump the minor version.
+A `Release-As: 0.3.0` commit footer sets the version explicitly.
+
+To release, merge the release PR once `All checks` passes. Release Please tags the
+merge commit and dispatches the Release workflow, which reruns CI on the tag,
+publishes to PyPI with attestations and publishes the GitHub release. Published
+versions are immutable; fix a bad release with a new version. To retry, rerun the
+failed jobs, or dispatch Release manually on the existing tag.
+
+PyPI accepts uploads through a
+[trusted publisher](https://docs.pypi.org/trusted-publishers/adding-a-publisher/),
+so no API token is stored:
+
+| Field | Value |
+| --- | --- |
+| PyPI project name | `sphinx-java-autodoc` |
+| GitHub owner | `r4sky0` |
+| Repository | `sphinx-java-autodoc` |
+| Workflow filename | `release.yml` |
+| Environment | `pypi` |
+
+GitHub Pages publishes the docs from each successful `main` build. Same-repository
+PRs get a preview at `pr-preview/pr-<number>/` after CI passes.

sphinx_java_autodoc-0.3.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.5
+Name: sphinx-java-autodoc
+Version: 0.3.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)
+[![PyPI](https://img.shields.io/pypi/v/sphinx-java-autodoc)](https://pypi.org/project/sphinx-java-autodoc/)
+[Documentation](https://r4sky0.github.io/sphinx-java-autodoc/)
+
+Publish your Java library's guides and API reference in one searchable Sphinx
+site. `sphinx-java-autodoc` reads your Java sources and Javadoc comments with the
+JDK compiler APIs and renders them as native Sphinx content:
+
+- Generated 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 cross-project links through intersphinx.
+- Content-based caching: pages refresh when sources change.
+
+Extraction never runs 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/alabaster/)
+for the output.
+
+## 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).
+
+## Quick start
+
+```sh
+uv add sphinx-java-autodoc
+```
+
+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
+```
+
+Next: [the first-build walkthrough](https://r4sky0.github.io/sphinx-java-autodoc/getting-started.html),
+[writing guides](https://r4sky0.github.io/sphinx-java-autodoc/guide.html),
+[dependencies and CI](https://r4sky0.github.io/sphinx-java-autodoc/build-integration.html) and the
+[configuration reference](https://r4sky0.github.io/sphinx-java-autodoc/usage.html).
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). [MIT licensed](LICENSE).

sphinx_java_autodoc-0.3.0/README.md

@@ -0,0 +1,57 @@
+# 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)
+[![PyPI](https://img.shields.io/pypi/v/sphinx-java-autodoc)](https://pypi.org/project/sphinx-java-autodoc/)
+[Documentation](https://r4sky0.github.io/sphinx-java-autodoc/)
+
+Publish your Java library's guides and API reference in one searchable Sphinx
+site. `sphinx-java-autodoc` reads your Java sources and Javadoc comments with the
+JDK compiler APIs and renders them as native Sphinx content:
+
+- Generated 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 cross-project links through intersphinx.
+- Content-based caching: pages refresh when sources change.
+
+Extraction never runs 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/alabaster/)
+for the output.
+
+## 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).
+
+## Quick start
+
+```sh
+uv add sphinx-java-autodoc
+```
+
+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
+```
+
+Next: [the first-build walkthrough](https://r4sky0.github.io/sphinx-java-autodoc/getting-started.html),
+[writing guides](https://r4sky0.github.io/sphinx-java-autodoc/guide.html),
+[dependencies and CI](https://r4sky0.github.io/sphinx-java-autodoc/build-integration.html) and the
+[configuration reference](https://r4sky0.github.io/sphinx-java-autodoc/usage.html).
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). [MIT licensed](LICENSE).

{sphinx_java_autodoc-0.2.1 → sphinx_java_autodoc-0.3.0}/SECURITY.md

@@ -1,7 +1,7 @@
 # Security
 
-Security fixes target the latest published version. Until the first publication,
-use the latest `main` commit and review the known limits in
+Security fixes target the latest version published on
+[PyPI](https://pypi.org/project/sphinx-java-autodoc/). Known limits are recorded in
 `docs/compatibility.rst`.
 
 Report vulnerabilities privately through

{sphinx_java_autodoc-0.2.1 → sphinx_java_autodoc-0.3.0}/docs/agents/domain.md

@@ -1,4 +1,4 @@
-# Domain Docs
+# Domain docs
 
 How the engineering skills should consume this repo's domain documentation when exploring the codebase.
 

{sphinx_java_autodoc-0.2.1 → sphinx_java_autodoc-0.3.0}/docs/alternatives.rst

@@ -1,13 +1,10 @@
-Choosing a tool
-===============
+Compare with other tools
+========================
 
 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>`_.
+always an option. The other tools were assessed in October 2026 from their
+documentation and source code, without running them. If something is out of date,
+please `open an issue <https://github.com/r4sky0/sphinx-java-autodoc/issues>`_.
 
 At a glance
 -----------

sphinx_java_autodoc-0.3.0/docs/build-integration.rst

@@ -0,0 +1,183 @@
+Add dependencies and publish
+============================
+
+Extraction needs the same sources and dependencies as your Java compiler. The
+extension never invokes Maven or Gradle, runs annotation processors or downloads
+dependencies, so prepare those inputs before running Sphinx.
+
+Choose where extraction runs
+----------------------------
+
+- **During Sphinx:** set ``java_sources`` and ``java_classpath`` in ``conf.py``.
+  The documentation builder needs JDK 25.
+- **Before Sphinx:** run the ``sphinx-java-autodoc`` command in your Java build and
+  pass its XML to Sphinx with ``java_model``. The Sphinx job needs no JDK.
+
+Dependencies and generated sources
+----------------------------------
+
+.. code-block:: python
+
+   java_sources = [
+       "../core/src/main/java",
+       "../client/src/main/java",
+       "../client/target/generated-sources/annotations",
+   ]
+   java_classpath = ["../lib/dependency.jar", "../other-module/target/classes"]
+   java_sourcepath = ["../dependency-sources"]
+   java_generate = "api"
+
+- ``java_sources`` takes several roots, so non-JPMS modules can share one site.
+  Leave out test sources unless they are part of your API.
+- ``java_classpath`` lists JARs and class directories explicitly; wildcards are not
+  expanded. A missing dependency produces a compiler error naming the symbol.
+- ``java_sourcepath`` adds dependency sources so their Javadoc can be inherited,
+  without generating pages for them. Its contents are part of the cache key.
+- Generate sources (annotation processors, templates) in your build first.
+  Lombok-like AST transformations are not supported.
+- JPMS ``module-info.java`` inputs are rejected; use non-modular source roots.
+
+Extract before Sphinx
+---------------------
+
+With JDK 25, from your project root:
+
+.. code-block:: console
+
+   sphinx-java-autodoc src/main/java --release 17 --warnings-as-errors \
+     --classpath-file build/classpath.txt --cache build/java-cache -o build/api.xml
+
+Then, in ``docs/conf.py``, without ``java_sources``:
+
+.. code-block:: python
+
+   extensions = ['sphinx_java_autodoc']
+   java_model = '../build/api.xml'
+   java_generate = 'api'
+
+CLI paths are relative to the working directory. ``--classpath`` takes a
+platform-separated path. ``--sourcepath`` and ``--exclude-package`` can repeat, and
+``--encoding`` matches ``java_encoding``. If compilation or a
+strict check fails, the previous output is kept. Your pipeline must rerun
+extraction when sources change, since Sphinx only sees the model.
+
+Maven
+-----
+
+Write the compile classpath with the
+`dependency plugin <https://maven.apache.org/plugins/maven-dependency-plugin/build-classpath-mojo.html>`_,
+then extract. With the repository's fixture:
+
+.. code-block:: console
+
+   mvn -f examples/maven/pom.xml -DskipTests compile \
+     org.apache.maven.plugins:maven-dependency-plugin:3.11.0:build-classpath \
+     -Dmdep.includeScope=compile -Dmdep.outputFile=target/classpath.txt
+   sphinx-java-autodoc examples/standalone/src examples/build-consumer/src \
+     examples/maven/target/generated-sources/java-autodoc \
+     --classpath-file examples/maven/target/classpath.txt \
+     -o build/maven-api.xml --cache build/java-cache --warnings-as-errors
+
+For your project, use ``src/main/java`` and your generated-source directories.
+
+Gradle
+------
+
+Write ``sourceSets.main.compileClasspath.asPath`` to a UTF-8 file, then extract.
+The fixture's ``examples/gradle/build.gradle`` has a ``writeJavaAutodocClasspath``
+task for this:
+
+.. code-block:: console
+
+   gradle -p examples/gradle classes writeJavaAutodocClasspath
+   sphinx-java-autodoc examples/standalone/src examples/build-consumer/src \
+     examples/gradle/build/generated/sources/java-autodoc \
+     --classpath-file examples/gradle/build/java-autodoc-classpath.txt \
+     -o build/gradle-api.xml --cache build/java-cache --warnings-as-errors
+
+Both fixtures are verified by ``uv run --locked python tests/build_tools_check.py``;
+see :doc:`compatibility` for the tested versions.
+
+Publish the site from CI
+------------------------
+
+This GitHub Actions workflow builds on every push to ``main`` and deploys to
+GitHub Pages. Set **Pages → Source** to **GitHub Actions** in the repository
+settings, then save it as ``.github/workflows/docs.yml``:
+
+.. code-block:: yaml
+
+   name: Documentation
+   on:
+     push:
+       branches: [main]
+
+   permissions:
+     contents: read
+
+   jobs:
+     build:
+       runs-on: ubuntu-latest
+       steps:
+         - uses: actions/checkout@v7
+           with:
+             persist-credentials: false
+         - uses: actions/setup-java@v6
+           with:
+             distribution: temurin
+             java-version: "25"
+         - uses: actions/setup-python@v7
+           with:
+             python-version: "3.12"
+         - run: python -m pip install sphinx-java-autodoc
+         # Prepare java_classpath inputs and generated sources here.
+         - run: sphinx-build -W --keep-going -n docs docs/_build/html
+         - uses: actions/upload-pages-artifact@v5
+           with:
+             path: docs/_build/html
+
+     deploy:
+       needs: build
+       runs-on: ubuntu-latest
+       permissions:
+         pages: write
+         id-token: write
+       environment:
+         name: github-pages
+         url: ${{ steps.deployment.outputs.page_url }}
+       steps:
+         - id: deployment
+           uses: actions/deploy-pages@v5
+
+Each run builds into a clean directory, so removed types leave no stale pages.
+The workflow passes ``actionlint`` but has not run in another repository.
+
+Caching and parallel builds
+---------------------------
+
+Sphinx caches extraction under ``<doctreedir>/java-cache`` and keeps only the
+current model. The CLI uses ``.java-autodoc-cache`` or ``--cache`` and never
+removes old entries.
+
+The cache key covers source and classpath contents, options, the JDK and the
+extension version. Every build hashes these inputs, so edits are caught even when
+timestamps are unchanged. Any change re-extracts the whole project and rereads
+every Sphinx document.
+
+``sphinx-build -j`` is supported. Separate Sphinx processes must not share a
+generated-page directory.
+
+Run the doclet directly
+-----------------------
+
+To run the bundled doclet without the Python wrapper's caching and safeguards.
+Its ``--sphinx-exclude`` option takes excluded packages separated by commas:
+
+.. code-block:: console
+
+   python -c "from sphinx_java_autodoc.extractor import DOCLET; print(DOCLET)"
+   javac -proc:none -encoding UTF-8 -d build/doclet /printed/path/SphinxDoclet.java
+   javadoc -quiet -encoding UTF-8 -protected \
+     -doclet sphinxjava.SphinxDoclet -docletpath build/doclet \
+     --sphinx-output build/api.xml -sourcepath src/main/java \
+     -classpath lib/dependency.jar com.example

{sphinx_java_autodoc-0.2.1 → sphinx_java_autodoc-0.3.0}/docs/compatibility.rst

@@ -1,16 +1,12 @@
 Compatibility and limits
 ========================
 
-This page is the single record of what has been tested and what is not supported.
-Configured CI jobs and recipes do not widen these claims until they have passed.
+What has been tested, and what is not supported. A configured CI job does not
+count until it has passed.
 
 Requirements and tested versions
 --------------------------------
 
-**Projects targeting Java 17, 21 and 25 are tested. Documentation extraction
-requires JDK 25**, even when your library builds and runs on an older Java release.
-Your library's own toolchain can stay as it is.
-
 .. list-table::
    :header-rows: 1
    :widths: 25 30 45
@@ -47,17 +43,12 @@ Your library's own toolchain can stay as it is.
      - Sphinx ``-j``
      - ``-j 2``, with an inventory identical to ``-j 1``
 
-Put JDK 25's ``java``, ``javac`` and ``javadoc`` on ``PATH``, or set ``java_jdk``
-to its home directory. A site that only renders a pre-extracted model or consumes
-another site's inventory needs no JDK.
-
 Not tested
 ----------
 
 * Other JDK runtimes, Sphinx releases, Firefox and WebKit, PDF/LaTeX and EPUB
   builders.
-* Large multi-module projects. A measured single-library workload is recorded in
-  :doc:`performance`; its warnings prevent a claim of complete Javadoc fidelity.
+* Large multi-module projects. :doc:`performance` records one single-library run.
 * Availability of remote Javadoc sites behind ``java_external_javadoc`` URLs.
 
 Known limits
@@ -71,9 +62,8 @@ Known limits
 * Only declared members are shown. Non-overridden inherited methods stay on their
   ancestor's page. Compiler-generated record and enum methods are listed, but the
   standard doclet's generated prose for them is not synthesized.
-* Signatures are display text rather than individually clickable type tokens.
-  Links in comments and explicit Java roles are native references. Manual Java
-  declaration directives are not provided.
+* Manual Java declaration directives are not provided; declarations come only
+  from the extracted model through the ``java:auto*`` directives.
 * External links use the Javadoc 9+ URL structure; Javadoc 8 member anchors are not
   supported. Roles mapped to external Javadoc without compiler metadata cannot
   check that the symbol exists.
@@ -90,17 +80,12 @@ Evidence
 --------
 
 The `CI workflow <https://github.com/r4sky0/sphinx-java-autodoc/actions/workflows/ci.yml>`_
-runs the operating system and Python matrix, the real JDK and Sphinx integration
-tests, packaging checks against the installed wheel, strict builds in six themes
-and the Chromium browser checks. Browser screenshots are kept as run artifacts.
-The integration tests compare constructor, generic, array and varargs anchors with
-actual standard Javadoc output, check byte-for-byte XML determinism across checkout
-locations, and confirm that extraction executes neither static initializers nor
-annotation processors.
+runs the operating system and Python matrix, the JDK and Sphinx integration tests
+against the installed wheel, strict builds and Chromium checks in five themes. The
+tests compare anchors with real standard-doclet output, check that the XML is
+byte-identical across checkout locations, and check that extraction runs neither
+static initializers nor annotation processors.
 
-Consumer builds executed on 2026-10-11: Maven 3.10.0 and Gradle 9.1.0, Temurin
-25.0.3, Python 3.12.13 and Sphinx 9.1.0 on macOS 26.4.1 arm64. Both compiled
-Commons Lang 3.21.0 consumers and a generated source, exported the dependency
-classpath, extracted strictly, and passed a strict parallel Sphinx build with an
-empty PATH. CI repeats the consumer check on Linux; its configured job alone is
-not additional validation evidence.
+The Maven and Gradle consumers last passed on 2026-10-11 with Maven 3.10.0,
+Gradle 9.1.0, Temurin 25.0.3, Python 3.12.13 and Sphinx 9.1.0 on macOS 26.4.1
+arm64, including a strict parallel Sphinx build with an empty ``PATH``.

{sphinx_java_autodoc-0.2.1 → sphinx_java_autodoc-0.3.0}/docs/conf.py

@@ -5,7 +5,23 @@ from pathlib import Path
 
 project = "Java autodoc"
 release = distribution_version("sphinx-java-autodoc")
-extensions = ["sphinx_java_autodoc", "sphinx.ext.intersphinx"]
+extensions = ["sphinx_java_autodoc", "sphinx.ext.intersphinx", "sphinx.ext.linkcode"]
+
+# The feature gallery documents the fixture API that the tests and browser checks use.
+java_sources = ["../examples/standalone/src"]
+java_generate = "gallery/api"
+
+
+def linkcode_resolve(domain, info):
+    # shortcut: links follow main, so a pull request preview may point at older lines;
+    # pass the built commit in if previews need exact lines.
+    if domain == "java" and info["line"]:
+        return (
+            "https://github.com/r4sky0/sphinx-java-autodoc/blob/main/"
+            f"examples/standalone/src/{info['source']}#L{info['line']}"
+        )
+    return None
+
 
 # The Java API shown here is the Commons Lang showcase, published next to these docs
 # at showcase/commons-lang/<theme>/; guides link to the Furo version. Its inventory

{sphinx_java_autodoc-0.2.1 → sphinx_java_autodoc-0.3.0}/docs/design.rst

@@ -1,9 +1,6 @@
 How it works
 ============
 
-For contributors and readers evaluating the implementation. To use the extension
-in your library, start with :doc:`getting-started`.
-
 Sphinx runs a small JDK doclet over your sources before reading documents. The
 doclet uses the compiler's view of declarations, overloads and Javadoc links and
 writes a versioned XML model. The extension turns that model into native Sphinx
@@ -17,15 +14,10 @@ dependencies, options and the JDK, so any change re-extracts the whole project.
 Design records
 --------------
 
-These live in the repository:
-
 * `Architecture decision and alternatives considered
   <https://github.com/r4sky0/sphinx-java-autodoc/blob/main/docs/adr/0001-jdk-doclet-xml-sphinx-domain.md>`_
 * `XML model schema
   <https://github.com/r4sky0/sphinx-java-autodoc/blob/main/docs/schema.md>`_
-* `Roadmap <https://github.com/r4sky0/sphinx-java-autodoc/blob/main/docs/roadmap.md>`_
-
-Tested environments and known limits are on :doc:`compatibility`.
 
 Contribute
 ----------

sphinx_java_autodoc-0.3.0/docs/gallery/comments.rst

@@ -0,0 +1,65 @@
+Javadoc comments
+================
+
+Comments are read from the compiler's comment trees and rendered as native Sphinx
+content, so your theme styles them like any other page. Source comments are never
+interpreted as reStructuredText, and no raw HTML is emitted.
+
+HTML, inline tags and snippets
+------------------------------
+
+One class comment uses most of the supported content: paragraphs, emphasis, nested
+lists, ``<pre>{@code ...}</pre>`` blocks, line breaks, external links, an inline
+``{@snippet}``, a table with a caption, ``{@value}``, ``{@link}`` and
+``{@linkplain}``, and the ``@see`` and ``@since`` tags.
+
+.. literalinclude:: ../../examples/standalone/src/demo/Widget.java
+   :language: java
+   :start-at: /** A widget
+   :end-at: public class Widget
+
+.. java:autoclass:: demo.Widget
+   :no-index:
+
+Parameters, returns and exceptions
+----------------------------------
+
+``@param``, ``@return`` and ``@throws`` become fields. Type parameters get their own
+field.
+
+.. literalinclude:: ../../examples/standalone/src/demo/Widget.java
+   :language: java
+   :start-at: /** Builds a generic index.
+   :end-at: List<? extends T> values
+
+.. java:automethod:: demo.Widget#buildIndex(java.util.List,java.util.Map)
+   :no-index:
+
+API and implementation notes
+----------------------------
+
+The JDK's ``@apiNote``, ``@implSpec`` and ``@implNote`` tags use the standard
+doclet's headings. ``@author`` and ``@version`` are left out, as the standard doclet
+does by default.
+
+.. literalinclude:: ../../examples/standalone/src/demo/Transformer.java
+   :language: java
+   :start-at: /** Transforms a value twice.
+   :end-at: default T twice
+
+.. java:automethod:: demo.Transformer#twice(java.lang.Object)
+   :no-index:
+
+Deprecation
+-----------
+
+``@deprecated`` produces the same notice as Sphinx's ``deprecated`` directive, and
+the annotation stays in the signature.
+
+.. literalinclude:: ../../examples/standalone/src/demo/Widget.java
+   :language: java
+   :start-at: /** Old entry point.
+   :end-at: public void old()
+
+.. java:automethod:: demo.Widget#old()
+   :no-index: