diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..3b46d615 --- /dev/null +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..5f26b043 --- /dev/null +++ b/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 diff --git a/README.md b/README.md index 90452e03..c341813a 100644 --- a/README.md +++ b/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 /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 diff --git a/build.gradle b/build.gradle index 180efdef..4aac700f 100644 --- a/build.gradle +++ b/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") +} diff --git a/src/doc/docs/contributing.md b/src/doc/docs/contributing.md new file mode 120000 index 00000000..c97564d9 --- /dev/null +++ b/src/doc/docs/contributing.md @@ -0,0 +1 @@ +../../../CONTRIBUTING.md \ No newline at end of file diff --git a/src/doc/docs/index.md b/src/doc/docs/index.md new file mode 100644 index 00000000..9d2230a6 --- /dev/null +++ b/src/doc/docs/index.md @@ -0,0 +1,3 @@ +# Welcome to exercism/java-analyzer + +Welcome to the Exercism Java analyzer documentation! 👋 diff --git a/src/doc/mkdocs.yml b/src/doc/mkdocs.yml new file mode 100644 index 00000000..f41a676b --- /dev/null +++ b/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