From b2391c28aa0aea59b7de32f672d6b699d3a5b31a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9dric=20Belin?= Date: Fri, 12 Apr 2024 09:49:55 +0200 Subject: [PATCH] Port the documentation to MkDocs --- .github/workflows/ci.yaml | 57 +++++++++++++++++++++++++++++++++ .github/workflows/main.yaml | 30 ------------------ .gitignore | 3 ++ build.xml | 22 +++++++------ docs/_sidebar.md | 6 ---- docs/index.html | 50 ----------------------------- docs/{README.md => index.md} | 6 +--- docs/styles.css | 4 +++ docs/usage/api.md | 28 +++++++++-------- docs/usage/cli.md | 2 +- etc/ivy.xml | 5 --- etc/mkdocs.yaml | 61 ++++++++++++++++++++++++++++++++++++ etc/requirements.txt | 1 + 13 files changed, 156 insertions(+), 119 deletions(-) create mode 100644 .github/workflows/ci.yaml delete mode 100644 .github/workflows/main.yaml delete mode 100644 docs/_sidebar.md delete mode 100644 docs/index.html rename docs/{README.md => index.md} (74%) create mode 100644 docs/styles.css delete mode 100644 etc/ivy.xml create mode 100644 etc/mkdocs.yaml create mode 100644 etc/requirements.txt diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml new file mode 100644 index 0000000..e15bcda --- /dev/null +++ b/.github/workflows/ci.yaml @@ -0,0 +1,57 @@ +name: continuous-integration +on: push + +jobs: + test: + runs-on: ${{matrix.os}} + strategy: + matrix: + os: [macos-latest, ubuntu-latest, windows-latest] + steps: + - name: Fetch sources + uses: actions/checkout@v4 + - name: Set up Java + uses: actions/setup-java@v4 + with: + distribution: temurin + java-version: 21 + - name: Set up Ant + uses: cedx/setup-ant@v2 + with: + optional-tasks: true + - name: Cache dependencies + uses: actions/cache@v4 + with: + path: ~/.ivy2/cache + key: ${{runner.os}}-ivy-${{hashFiles('**/ivy.xml')}} + restore-keys: ${{runner.os}}-ivy- + - name: Install dependencies + run: ant install + - name: Run tests + run: ant -emacs test + deploy: + needs: test + runs-on: ubuntu-latest + steps: + - name: Fetch sources + uses: actions/checkout@v4 + - name: Set up Java + uses: actions/setup-java@v4 + with: + distribution: temurin + java-version: 21 + - name: Set up Ant + uses: cedx/setup-ant@v2 + with: + optional-tasks: true + - name: Set up Python + uses: actions/setup-python@v5 + with: + cache: pip + python-version: 3.12 + - name: Install dependencies + run: pip install --requirement=etc/requirements.txt + - name: Deploy documentation + run: | + ant doc + mkdocs gh-deploy --config-file=etc/mkdocs.yaml --force diff --git a/.github/workflows/main.yaml b/.github/workflows/main.yaml deleted file mode 100644 index 8fe6d02..0000000 --- a/.github/workflows/main.yaml +++ /dev/null @@ -1,30 +0,0 @@ -name: main -on: push -jobs: - test: - runs-on: ${{matrix.os}} - strategy: - matrix: - os: [macos-latest, ubuntu-latest, windows-latest] - steps: - - name: Fetch sources - uses: actions/checkout@v4 - - name: Set up Java - uses: actions/setup-java@v4 - with: - distribution: temurin - java-version: 21 - - name: Set up Ant - uses: cedx/setup-ant@v2 - with: - optional-tasks: true - - name: Cache dependencies - uses: actions/cache@v4 - with: - path: lib - key: java-${{runner.os}}-ivy-${{hashFiles('ivy.xml')}} - restore-keys: java-${{runner.os}}-ivy- - - name: Install dependencies - run: ant install - - name: Run tests - run: ant -emacs test diff --git a/.gitignore b/.gitignore index 638564d..5b9e26e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,10 @@ /**/.DS_Store /.idea/ +/*.iml /bin/ +/docs/api/ /etc/http-client.private.env.json /lib/ /src/picocli/ /var/ +/www/ diff --git a/build.xml b/build.xml index e56387b..6a74ce8 100644 --- a/build.xml +++ b/build.xml @@ -9,14 +9,13 @@ ${project.title} ${project.version} - - + @@ -28,7 +27,7 @@ - + @@ -60,15 +59,14 @@ - + - - + @@ -84,7 +82,7 @@ - + @@ -97,11 +95,17 @@ - + + + + + + + @@ -115,7 +119,7 @@ - + diff --git a/docs/_sidebar.md b/docs/_sidebar.md deleted file mode 100644 index d6d4aaa..0000000 --- a/docs/_sidebar.md +++ /dev/null @@ -1,6 +0,0 @@ -- Usage - - [Programming interface](usage/api.md) - - [Command line](usage/cli.md) -- [API reference](api/) -- [Changelog](changelog.md) -- [License](license.md) diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index fd4edee..0000000 --- a/docs/index.html +++ /dev/null @@ -1,50 +0,0 @@ - - - - - Which for Java - - - - - - - - - - - - - - - - - - - - - - - - - -
- - diff --git a/docs/README.md b/docs/index.md similarity index 74% rename from docs/README.md rename to docs/index.md index ef15cc4..f4ec7e3 100644 --- a/docs/README.md +++ b/docs/index.md @@ -3,7 +3,7 @@ Find the instances of an executable in the system path, in [Java](https://www.or ## Quick start Download the latest JAR file of **Which for Java** from the GitHub releases: -https://github.com/cedx/which.java/releases/latest +[https://github.com/cedx/which.java/releases/latest](https://github.com/cedx/which.java/releases/latest) Add it to your class path. Now in your [Java](https://www.oracle.com/java) code, you can use: @@ -14,7 +14,3 @@ import io.belin.which.*; ## Usage - [Application programming interface](usage/api.md) - [Command line interface](usage/cli.md) - -## See also -- [API reference](api/) -- [GitHub releases](https://github.com/cedx/which.java/releases) diff --git a/docs/styles.css b/docs/styles.css new file mode 100644 index 0000000..ff5dd9a --- /dev/null +++ b/docs/styles.css @@ -0,0 +1,4 @@ +body { + --md-code-font-family: ui-monospace, monospace; + --md-text-font-family: ui-sans-serif, sans-serif; +} diff --git a/docs/usage/api.md b/docs/usage/api.md index b2ebf74..341fddd 100644 --- a/docs/usage/api.md +++ b/docs/usage/api.md @@ -64,31 +64,33 @@ class Program { ## Options The behavior of the `Finder.which(String command, List paths, List extensions)` method can be customized using the following parameters. -### List<Path> **paths** -A [`List`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/List.html) -of [`Path`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/nio/file/Path.html)s specifying the system paths -from which the given command will be searched. +### List<String> **extensions** +A [`List`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/List.html) of strings specifying the executable file extensions. -Defaults to the list of directories provided by the `PATH` environment variable. +On Windows, defaults to the list of extensions provided by the `PATHEXT` environment variable. ```java import static io.belin.which.Finder.which; -import java.nio.file.Path; import java.util.List; -which("foobar", List.of(Path.of("/usr/local/bin"), Path.of("/usr/bin"))); +which("foobar", null, List.of(".foo", ".exe", ".cmd")); ``` -### List<String> **extensions** -A [`List`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/List.html) of strings specifying the executable file extensions. +!!! note + The `extensions` option is only meaningful on the Windows platform, + where the executability of a file is determined from its extension. -On Windows, defaults to the list of extensions provided by the `PATHEXT` environment variable. +### List<Path> **paths** +A [`List`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/List.html) +of [`Path`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/nio/file/Path.html)s specifying the system paths +from which the given command will be searched. + +Defaults to the list of directories provided by the `PATH` environment variable. ```java import static io.belin.which.Finder.which; +import java.nio.file.Path; import java.util.List; -which("foobar", null, List.of(".foo", ".exe", ".cmd")); +which("foobar", List.of(Path.of("/usr/local/bin"), Path.of("/usr/bin"))); ``` - -> The `extensions` option is only meaningful on the Windows platform, where the executability of a file is determined from its extension. diff --git a/docs/usage/cli.md b/docs/usage/cli.md index 00e3ea2..0b208b4 100644 --- a/docs/usage/cli.md +++ b/docs/usage/cli.md @@ -1,6 +1,6 @@ # Command line interface Download the latest `cli` JAR file of **Which for Java** from the GitHub releases: -https://github.com/cedx/which.java/releases/latest +[https://github.com/cedx/which.java/releases/latest](https://github.com/cedx/which.java/releases/latest) Then use it to find the instances of an executable command: diff --git a/etc/ivy.xml b/etc/ivy.xml deleted file mode 100644 index 416358c..0000000 --- a/etc/ivy.xml +++ /dev/null @@ -1,5 +0,0 @@ - - - - - diff --git a/etc/mkdocs.yaml b/etc/mkdocs.yaml new file mode 100644 index 0000000..777d0f5 --- /dev/null +++ b/etc/mkdocs.yaml @@ -0,0 +1,61 @@ +site_name: Which for Java +site_url: https://docs.belin.io/which.java +site_author: Cédric Belin - cedric@belin.io +site_description: > + Find the instances of an executable in the system path, in Java. + Like the `which` Linux command. + +docs_dir: ../docs +site_dir: ../www +use_directory_urls: false + +edit_uri: edit/main/docs/ +repo_name: cedx/which.java +repo_url: https://github.com/cedx/which.java + +copyright: Copyright © Cédric Belin +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/cedx + name: GitHub + - icon: fontawesome/brands/linkedin + link: https://linkedin.com/in/cedxbelin + name: LinkedIn + - icon: fontawesome/brands/mastodon + link: https://mastodon.social/@cedx + name: Mastodon + +extra_css: + - styles.css + +markdown_extensions: + - admonition + - pymdownx.superfences + +nav: + - Home: index.md + - Usage: + - Programming interface: usage/api.md + - Command line: usage/cli.md + - See also: + - API reference: api/ + - Changelog: changelog.md + - License: license.md + +theme: + favicon: favicon.svg + features: + - content.code.copy + - content.tooltips + - navigation.footer + - navigation.instant + - navigation.instant.progress + - navigation.sections + - search.suggest + font: false + logo: favicon.svg + name: material + palette: + accent: red + primary: red diff --git a/etc/requirements.txt b/etc/requirements.txt new file mode 100644 index 0000000..4c8f017 --- /dev/null +++ b/etc/requirements.txt @@ -0,0 +1 @@ +mkdocs-material