docs: add programming guide

.yarnrc.yml

@@ -35,6 +35,9 @@ packageExtensions:
       "@algolia/client-search": "*"
       search-insights: "*"
       typescript: "*"
+  "@docusaurus/plugin-client-redirects@*":
+    peerDependencies:
+      typescript: "*"
   "@docusaurus/plugin-content-blog@*":
     peerDependencies:
       typescript: "*"

subprojects/docs/docusaurus.config.ts

@@ -5,7 +5,10 @@
  * SPDX-License-Identifier: MIT AND EPL-2.0
  */
 
+import path from 'node:path';
+
 import type { MDXOptions } from '@docusaurus/mdx-loader';
+import type { Options as RedirectOptions } from '@docusaurus/plugin-client-redirects';
 import type { Options as DocsOptions } from '@docusaurus/plugin-content-docs';
 import type { Options as PagesOptions } from '@docusaurus/plugin-content-pages';
 import type { Options as ClassicThemeOptions } from '@docusaurus/theme-classic';
@@ -17,9 +20,17 @@ import { themes } from 'prism-react-renderer';
 import smartypants from 'remark-smartypants';
 
 import remarkPosix2Windows from './src/plugins/remarkPosix2Windows';
+import remarkReplaceVariables from './src/plugins/remarkReplaceVariables';
 
 const markdownOptions: Partial<MDXOptions> = {
-  remarkPlugins: [[smartypants, { dashes: 'oldschool' }], remarkPosix2Windows],
+  remarkPlugins: [
+    [
+      remarkReplaceVariables,
+      { propertiesPath: path.join(__dirname, '../../gradle.properties') },
+    ],
+    [smartypants, { dashes: 'oldschool' }],
+    remarkPosix2Windows,
+  ],
 };
 
 const docsOptions = {
@@ -60,6 +71,17 @@ export default {
       '@docusaurus/plugin-content-pages',
       markdownOptions satisfies PagesOptions,
     ],
+    [
+      '@docusaurus/plugin-client-redirects',
+      {
+        redirects: [
+          {
+            to: '/develop/java/',
+            from: '/develop/',
+          },
+        ],
+      } satisfies RedirectOptions,
+    ],
     '@docusaurus/plugin-sitemap',
     './src/plugins/loadersPlugin.ts',
     './src/plugins/swcMinifyPlugin.ts',
@@ -78,7 +100,7 @@ export default {
       respectPrefersColorScheme: true,
     },
     prism: {
-      additionalLanguages: ['bash', 'java'],
+      additionalLanguages: ['bash', 'groovy', 'java', 'kotlin'],
       theme: themes.oneLight,
       darkTheme: themes.oneDark,
     },
@@ -96,7 +118,7 @@ export default {
         },
         {
           label: 'Develop',
-          to: '/develop',
+          to: '/develop/java',
         },
         {
           label: 'GitHub',
@@ -139,7 +161,7 @@ export default {
           items: [
             {
               label: 'Programming guide',
-              to: '/develop',
+              to: '/develop/java',
             },
             {
               label: 'Contributing',

subprojects/docs/package.json

@@ -32,6 +32,7 @@
   "dependencies": {
     "@algolia/client-search": "^4.24.0",
     "@docusaurus/core": "^3.4.0",
+    "@docusaurus/plugin-client-redirects": "^3.4.0",
     "@docusaurus/plugin-content-docs": "^3.4.0",
     "@docusaurus/plugin-content-pages": "^3.4.0",
     "@docusaurus/plugin-sitemap": "^3.4.0",
@@ -45,6 +46,7 @@
     "@mdx-js/react": "^3.0.1",
     "@swc/core": "^1.6.13",
     "clsx": "^2.1.1",
+    "java-properties": "^1.0.2",
     "mdast-util-mdx": "^3.0.0",
     "prism-react-renderer": "^2.3.1",
     "react": "^18.3.1",

subprojects/docs/src/develop/contributing/commands.md

@@ -36,20 +36,7 @@ This will also be run by GitHub Actions for each commit or pull requests.
 Publishes the Refinery Java artifacts to the [Maven local repository](https://www.baeldung.com/maven-local-repository).
 
 Build tools, such as Gradle, will be able to consume such artifacts, which enables you to use the latest version of Refinery -- possibly including your own modification -- in other Java projects.
-
-For example, in Gradle, you may set
-
-```kotlin title="build.gradle.kts"
-repositories {
-  mavenLocal()
-}
-
-dependencies {
-  implementation("tools.refinery:refinery-generator:0.0.0-SNAPSHOT")
-}
-```
-
-to add a dependency on Refinery to your Java project.
+For more information, see our [programming guide](../../java).
 
 ### `serve`
 

subprojects/docs/src/develop/contributing/ide-setup.md

@@ -12,15 +12,15 @@ title: IDE setup
 We prefer [IntelliJ IDEA](https://www.jetbrains.com/idea/) as a Java development environment.
 No special preparations should be necessary for importing the project as a Gradle project into IDEA:
 
-1. See the [required tools](/develop/contributing#required-tools) for compiling Refinery about obtaining the required JDK version. You'll also need a version of IntelliJ IDEA that supports **Java 21** (version **2023.3** or later).
+1. See the [required tools](/develop/contributing#required-tools) for compiling Refinery on obtaining the required JDK version. You'll also need a version of IntelliJ IDEA that supports **Java 21** (version **2023.3** or later).
 
 2. Clone the project git repository and open it in IntelliJ IDEA. Make sure to _open_ the project instead of creating a _new_ one in the same directory.
 
 3. IntelliJ IDEA should build and index the project. If there are errors, it is likely that the `JAVA_HOME` was incorrectly set:
     * In _Project Structure > Project settings > Project > SDK_, a Java 21 compatible JDK should be selected.
     * In _Project Structure > Project settings > Project > Language level_, either _SDK default_ or _21_ should be selected.
     * Make sure that each module in _Project Structure > Project settings > Module_ uses the _Project default_ language level in _Sources > Language level_ and the _Project SDK_ in _Dependencies > Module SDK._
-    * In _Settings > Gradle settings > Gralde Projects > Gradle_, the _Distribution_ should be set to _Wrapper_ and the _Gradle JVM_ should be set to _Project SDK._
+    * In _Settings > Gradle settings > Gradle Projects > Gradle_, the _Distribution_ should be set to _Wrapper_ and the _Gradle JVM_ should be set to _Project SDK._
 
 4. We recommend installing the latest _SonarLint_ plugin in _Settings > Plugins_ to get real-time code quality analysis in your IDE.
 
@@ -35,7 +35,7 @@ You'll also need [VS Code](#vs-code) to edit the TypeScript code in Refinery.
 
 ## Eclipse
 
-1. See the [required tools](/develop/contributing#required-tools) for compiling Refinery about obtaining the required JDK version.
+1. See the [required tools](/develop/contributing#required-tools) for compiling Refinery on obtaining the required JDK version.
 
 2. Download and extract the [Eclipse IDE for Java and DSL Developers 2023-12](https://www.eclipse.org/downloads/packages/release/2023-12/r/eclipse-ide-java-and-dsl-developers) package.
 
@@ -63,7 +63,7 @@ You'll also need [VS Code](#vs-code) to edit the TypeScript code in Refinery.
     ```
     in the cloned repository.
     * This should complete without any compilation errors.
-    * To troubleshoot any error, see the [instructions about compiling Refinery](/develop/contributing#compiling).
+    * To troubleshoot any error, see the [instructions for compiling Refinery](/develop/contributing#compiling).
 
 8. Select _File > Import... > Gradle > Existing Gradle Project_ and import the cloned repository in Eclipse.
     * Make sure to select the root of the repository (containing this file) as the _Project root directory_ and that the _Gradle distribution_ is _Gradle wrapper_.
@@ -73,7 +73,7 @@ You'll also need [VS Code](#vs-code) to edit the TypeScript code in Refinery.
 
 We recommend [VSCodium](https://github.com/VSCodium/vscodium) or [Visual Studio Code](https://code.visualstudio.com/) to work with the parts of Refinery that are written is TypeScript.
 
-1. See the [required tools](/develop/contributing#required-tools) for compiling Refinery about obtaining the required JDK version. You'll also need a version of IntelliJ IDEA that supports **Java 21** (version **2023.3** or later).
+1. See the [required tools](/develop/contributing#required-tools) for compiling Refinery on obtaining the required JDK version.
 
 2. Install the following VS Code extensions:
     * _EditorConfig for VS Code_ [[Open VSX](https://open-vsx.org/extension/EditorConfig/EditorConfig)] [[Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig)]