Port the documentation to MkDocs

.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

.gitignore

@@ -1,7 +1,10 @@
 /**/.DS_Store
 /.idea/
+/*.iml
 /bin/
+/docs/api/
 /etc/http-client.private.env.json
 /lib/
 /src/picocli/
 /var/
+/www/

build.xml

@@ -9,14 +9,13 @@
 	<property name="vendor.name" value="Cédric Belin"/>
 
 	<description>${project.title} ${project.version}</description>
-	<ivy:settings file="etc/ivy.xml" unless:true="${env.GITHUB_ACTIONS}"/>
 
 	<path id="project.classpath">
 		<pathelement location="bin"/>
 		<fileset dir="lib" excludes="*-javadoc.jar,*-sources.jar" includes="*.jar"/>
 	</path>
 
-	<target name="build" description="Builds the project.">
+	<target name="build" description="Builds the project">
 		<unzip dest="src">
 			<fileset dir="lib" includes="picocli-*-sources.jar"/>
 			<patternset includes="**/CommandLine.java"/>
@@ -28,7 +27,7 @@
 		</javac>
 	</target>
 
-	<target name="clean" description="Deletes all generated files.">
+	<target name="clean" description="Deletes all generated files">
 		<delete failonerror="false" includeEmptyDirs="true">
 			<fileset dir="bin" excludes="*.ps1"/>
 			<fileset dir="src/picocli"/>
@@ -60,15 +59,14 @@
 		</jar>
 	</target>
 
-	<target name="doc" description="Builds the documentation.">
+	<target name="doc" description="Builds the documentation" depends="build">
 		<copy file="CHANGELOG.md" toFile="docs/changelog.md"/>
 		<copy file="LICENSE.md" toFile="docs/license.md"/>
 		<delete dir="docs/api"/>
 		<javadoc sourcePath="src" destDir="docs/api" packageNames="${vendor.id}.*" windowTitle="${project.title}"/>
-		<copy file="docs/favicon.ico" toDir="docs/api"/>
 	</target>
 
-	<target name="install" description="Installs the project dependencies.">
+	<target name="install" description="Installs the project dependencies">
 		<mkdir dir="lib"/>
 		<ivy:retrieve log="download-only" sync="true"/>
 	</target>
@@ -84,7 +82,7 @@
 		</java>
 	</target>
 
-	<target name="outdated" description="Checks whether installed packages are out of date.">
+	<target name="outdated" description="Checks whether installed packages are out of date">
 		<ivy:checkdepsupdate log="quiet"/>
 	</target>
 
@@ -97,11 +95,17 @@
 		</exec>
 	</target>
 
-	<target name="run" description="Runs a main class from the &quot;example&quot; folder.">
+	<target name="run" description="Runs a main class from the &quot;example&quot; folder">
 		<fail message="You must specify an example to run using -Dclass=&lt;example&gt;." unless="class"/>
 		<java sourceFile="example/${class}.java" classPathRef="project.classpath" failOnError="true" fork="true"/>
 	</target>
 
+	<target name="serve" description="Starts the development server" depends="doc">
+		<exec executable="mkdocs">
+			<arg line="serve --config-file=etc/mkdocs.yaml"/>
+		</exec>
+	</target>
+
 	<target name="test" description="Runs the test suite." depends="build">
 		<javac srcDir="test" destDir="bin" classPathRef="project.classpath" includeAntRuntime="false">
 			<compilerarg value="-proc:full"/>
@@ -115,7 +119,7 @@
 		</java>
 	</target>
 
-	<target name="version" description="Updates the version number in the sources.">
+	<target name="version" description="Updates the version number in the sources">
 		<replaceregexp file="README.md" match="project/v\d+(\.\d+){2}" replace="project/v${project.version}"/>
 	</target>
 </project>

docs/README.md → 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)

docs/styles.css

@@ -0,0 +1,4 @@
+body {
+	--md-code-font-family: ui-monospace, monospace;
+	--md-text-font-family: ui-sans-serif, sans-serif;
+}

docs/usage/api.md

@@ -64,31 +64,33 @@ class Program {
 ## Options
 The behavior of the `Finder.which(String command, List<Path> paths, List<String> extensions)` method can be customized using the following parameters.
 
-### List&lt;Path&gt; **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&lt;String&gt; **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&lt;String&gt; **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&lt;Path&gt; **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.

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:
 

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 - [email protected]
+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

etc/requirements.txt

@@ -0,0 +1 @@
+mkdocs-material