Add documentation

.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Build documentation
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+      - name: Set up JDK
+        uses: actions/setup-java@387ac29b308b003ca37ba93a6cab5eb57c8f5f93
+        with:
+          java-version: "21"
+          distribution: "temurin"
+      - name: Set up Python
+        uses: actions/setup-python@0a5c61591373683505ea898e09a3ea4f39ef2b9c
+        with:
+          python-version: "3.11"
+      - name: Build documentation
+        run: ./gradlew --no-daemon clean mkdocsBuild javadoc
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@0252fc4ba7626f0298f0cf00902a25c6afc77fa8
+        if: ${{ github.ref == 'refs/heads/main' }}
+        with:
+          path: build/docs
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-22.04
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@87c3283f01cd6fe19a0ab93a23b2f6fcba5a8e42

CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing
+
+Thank you so much for contributing! 🎉
+
+We welcome contributions of all sorts and sizes, from reporting issues to submitting patches, as well as joining discussions on the [Java forum][java-forum].
+
+Unprompted (without an issue) PRs with small bugfixes are welcome.
+However, if you want to propose bigger changes, make sure to post on the [forum][java-forum] first so that we can discuss it.
+
+## Code of Conduct
+
+Help us keep Exercism welcoming.
+Please read and abide by the [Code of Conduct][coc].
+
+## Contributing to Exercism
+
+If you are new to contributing to Exercism, please read:
+
+- [Being a good community member][community-docs]
+- [Contributing via GitHub][contributing-docs-github]
+
+## How does this project work?
+
+Start by reading up on Exercism analyzers:
+
+- [The analyzer interface][analyzer-docs-interface]
+- [Guidance on implementing analyzers][analyzer-docs-guidance]
+
+To learn how the Java Analyzer works:
+
+- Browse [existing exercise analyzer implementations][browse-analyzers].
+
+### Writing comments
+
+All the Analyzer comments for all tracks are stored together in [exercism/website-copy][analyzer-comments].
+When adding a new Analyzer check with a new comment, you need to open a corresponding PR in [exercism/website-copy][analyzer-comments] with that comment's content.
+
+See [the Analyzer comment guidelines][analyzer-comments-guidelines] for guidance on how to write friendly and constructive Analyzer comments.
+
+[coc]: https://github.com/exercism/java-analyzer/blob/main/CODE_OF_CONDUCT.md
+[analyzer-comments]: https://github.com/exercism/website-copy/tree/main/analyzer-comments
+[analyzer-comments-guidelines]: https://exercism.org/docs/building/tooling/analyzers/comments
+[java-forum]: https://forum.exercism.org/c/programming/java/91
+[browse-analyzers]: https://github.com/exercism/java-analyzer/tree/main/src/main/java/analyzer/exercises/
+[analyzer-docs-guidance]: https://exercism.org/docs/building/tooling/analyzers/guidance
+[analyzer-docs-interface]: https://exercism.org/docs/building/tooling/analyzers/interface
+[community-docs]: https://exercism.org/docs/community/being-a-good-community-member
+[contributing-docs-github]: https://exercism.org/docs/building/github

README.md

@@ -1,16 +1,65 @@
 # Java Analyzer [![Coverage Status](https://coveralls.io/repos/github/exercism/java-analyzer/badge.svg?branch=main)](https://coveralls.io/github/exercism/java-analyzer?branch=main)
 
-The Java track project-auto-mentor analyzer using abstract syntax trees.
+The Java analyzer uses [Abstract Syntax Trees][ast-wiki] (ASTs) to analyze submitted solutions using the [`javaparser`][javaparser] library.
 
+## Contributing
 
-## Running in docker
+If you want to contribute to the Java analyzer, please refer to the [Contributing Guide][contributing-guide].
 
-To analyze a solution in docker,
-1. Build the image
+## Usage
+
+### Running directly
+
+Start by building the JAR using Gradle:
+
+```sh
+./gradlew build
+```
+
+Then, run the Java analyzer using `build/libs/java-analyzer.jar`.
+For example, to analyze a solution for the `leap` exercise, run:
+
+```sh
+java -jar build/libs/java-analyzer.jar leap /path/to/leap/ /path/to/output/folder/
 ```
+
+The analyzer output is written to `analysis.json` and `tags.json` in `/path/to/output/folder/`.
+
+### Running with Docker
+
+To run the Java analyzer using Docker, first build and tag the Docker image:
+
+```sh
 docker build -t exercism/java-analyzer .
 ```
-2. Run the image
+
+Then, run the image and mount the directory of the solution to analyze.
+For example, to analyze a solution for the `leap` exercise located at `~/exercism/java/leap`, run:
+
+```sh
+docker run -v /path/to/leap:/input -v /path/to/output/folder:/output exercism/java-analyzer leap /input/ /output/
+```
+
+The analyzer output is written to `analysis.json` and `tags.json` in `/path/to/output/folder/`.
+
+## Tests
+
+### Unit tests
+
+To run the unit tests:
+
+```sh
+./gradlew test
 ```
-docker run -v <~/a/local/solution>:/solution exercism/java-analyzer <slug> /solution
+
+### Smoke tests
+
+To run the smoke tests using Docker:
+
+```sh
+bin/run-tests-in-docker.sh
 ```
+
+[ast-wiki]: https://en.wikipedia.org/wiki/Abstract_syntax_tree
+[contributing-guide]: https://github.com/exercism/java-analyzer/blob/main/CONTRIBUTING.md
+[javaparser]: https://github.com/javaparser/javaparser 

build.gradle

@@ -1,8 +1,9 @@
 plugins {
-    id "com.github.johnrengelman.shadow" version "8.1.1"
     id "java"
     id "application"
     id "jacoco"
+    id "com.github.johnrengelman.shadow" version "8.1.1"
+    id "ru.vyarus.mkdocs-build" version '3.0.0'
 }
 
 group = "org.exercism"
@@ -49,3 +50,14 @@ jacocoTestReport {
         xml.required = true
     }
 }
+
+mkdocs {
+    sourcesDir = "src/doc"
+    buildDir = file("build/docs")
+    publish.docPath = null
+}
+
+javadoc {
+    mustRunAfter(mkdocsBuild)
+    destinationDir = file("build/docs/api")
+}

src/doc/docs/contributing.md

@@ -0,0 +1 @@
+../../../CONTRIBUTING.md

src/doc/docs/index.md

@@ -0,0 +1,3 @@
+# Welcome to exercism/java-analyzer
+
+Welcome to the Exercism Java analyzer documentation! 👋

src/doc/mkdocs.yml

@@ -0,0 +1,43 @@
+site_name: Exercism Java analyzer
+
+site_description: Documentation for the Exercism Java analyzer
+site_url: https://exercism.github.io/java-analyzer
+
+repo_name: java-analyzer
+repo_url: https://github.com/exercism/java-analyzer
+edit_uri: blob/main/docs/src/
+
+copyright: 'Copyright © 2024 Exercism'
+
+theme:
+  name: material
+  palette:
+    # Palette toggle for light mode
+    - scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.path
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.top
+    - navigation.tracking
+
+markdown_extensions:
+  - admonition
+  - fenced_code
+  - footnotes
+  - tables
+  - toc:
+      permalink: true
+
+nav:
+  - Home: index.md
+  - contributing.md
+  - API: /java-analyzer/api