Merge pull request #20 from railsware/feature/docfx-api-reference

Added DocFX to create API References site

Author: vitalii-t

.github/workflows/javadoc-publish.yml

@@ -7,7 +7,7 @@ on:
 
 jobs:
   build:
-    name: Build Javadocs
+    name: Build Javadocs and DocFX Site
 
     runs-on: ubuntu-latest
 
@@ -21,17 +21,31 @@ jobs:
           java-version: 17
           distribution: 'temurin'
 
+      - name: Install .NET SDK # required for DocFX as a .NET tool
+        uses: actions/setup-dotnet@v4
+
+      - name: Install DocFX Tool
+        run: dotnet tool install -g docfx
+
       - name: Install dependencies and generate Javadocs
         run: mvn clean install -B -q -Dgpg.skip=true javadoc:javadoc javadoc:jar
 
+      - name: Build Documentation Site
+        run: docfx ./docs/docfx.json
+
+      - name: Copy Javadocs to _site/api-docs
+        run: |
+          mkdir -p docs/_site/java-docs
+          mv -v target/reports/apidocs/* docs/_site/java-docs/
+
       # Upload the Javadocs as an artifact to be deployed
-      - name: Upload Javadocs Artifact
+      - name: Upload Artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: target/reports/apidocs
+          path: docs/_site
 
   deploy:
-    name: Deploy Javadocs to GitHub Pages
+    name: Deploy to GitHub Pages
 
     runs-on: ubuntu-latest
     needs: build

docs/docfx.json

@@ -0,0 +1,18 @@
+{
+  "build": {
+    "globalMetadata": {
+      "_appLogoPath": "images/logo.png"
+    },
+    "content": [
+      {
+        "files": ["*.md", "**.md", "toc.yml"]
+      }
+    ],
+    "resource": [
+      {
+        "files": ["images/*"]
+      }
+    ],
+    "dest": "_site"
+  }
+}

docs/getting-started.md

@@ -0,0 +1,76 @@
+# Quick Start
+
+Follow these few simple steps to add Mailtrap API functionality into your Java project.
+
+# Prerequisites
+
+Make sure your project uses JDK 11 or higher
+
+## Setup
+
+### 1. Add the library as a Maven/Gradle dependency
+Maven dependency
+
+```xml
+
+<dependency>
+    <groupId>io.mailtrap</groupId>
+    <artifactId>mailtrap-java</artifactId>
+    <version>*latest-version*</version>
+</dependency>
+```
+
+Gradle Groovy dependency
+
+```groovy
+implementation 'io.mailtrap:mailtrap-java:*latest-version*'
+```
+
+Gradle Kotlin DSL dependency
+
+```kotlin
+implementation("io.mailtrap:mailtrap-java:*latest-version*")
+```
+
+### 2. Register/login into Mailtrap account
+Obtain API token to configure and use MailtrapClient
+
+### 3. Configuration and usage
+
+```java
+import io.mailtrap.client.MailtrapClient;
+import io.mailtrap.config.MailtrapConfig;
+import io.mailtrap.factory.MailtrapClientFactory;
+import io.mailtrap.model.request.emails.Address;
+import io.mailtrap.model.request.emails.MailtrapMail;
+
+import java.util.List;
+
+public class Minimal {
+
+    private static final String TOKEN = "<YOUR MAILTRAP TOKEN>";
+    private static final String SENDER_EMAIL = "[email protected]";
+    private static final String RECIPIENT_EMAIL = "[email protected]";
+
+    public static void main(String[] args) {
+        final MailtrapConfig config = new MailtrapConfig.Builder()
+                .token(TOKEN)
+                .build();
+
+        final MailtrapClient client = MailtrapClientFactory.createMailtrapClient(config);
+
+        final MailtrapMail mail = MailtrapMail.builder()
+                .from(new Address(SENDER_EMAIL))
+                .to(List.of(new Address(RECIPIENT_EMAIL)))
+                .subject("Hello from Mailtrap Sending!")
+                .text("Welcome to Mailtrap!")
+                .build();
+
+        try {
+            System.out.println(client.send(mail));
+        } catch (Exception e) {
+            System.out.println("Caught exception : " + e);
+        }
+    }
+}
+```

docs/images/logo.png

@@ -0,0 +1,18 @@
+---
+_layout: landing
+---
+# Official Mailtrap Java Client
+
+Welcome to the documentation portal for the official <a href="https://mailtrap.io/" target="_blank">Mailtrap</a> Java client!
+
+This client allows you to quickly and easily integrate your Java application with Mailtrap API.
+
+
+## Table of contents
+
+- [Getting Started](getting-started.md) - quick overview on how to integrate Mailtrap into your project
+- [Usage Examples](usage-examples.md) 
+- [API Reference](javadocs.md) - Detailed API Reference
+
+## License
+Licensed under the <a href="https://github.com/railsware/mailtrap-java/blob/main/LICENSE.txt" target="_blank">MIT License</a>.

docs/index.md

@@ -0,0 +1,3 @@
+# Detailed Java API Reference
+
+View the <a href="./java-docs/index.html" target="_blank">Java API Documentation</a>.

docs/javadocs.md

@@ -0,0 +1,8 @@
+- name: Home
+  href: index.md
+- name: Getting Started
+  href: getting-started.md
+- name: Usage Examples
+  href: usage-examples.md
+- name: API Reference
+  href: javadocs.md

docs/toc.yml

@@ -0,0 +1,3 @@
+# Detailed Usage Examples
+
+Code examples, that covers all possible APIs can be found <a href="https://github.com/railsware/mailtrap-java/tree/main/examples/java/io/mailtrap/examples" target="_blank">here</a>

docs/usage-examples.md

@@ -194,6 +194,22 @@
                             <goal>jar</goal>
                         </goals>
                     </execution>
+                    <execution>
+                        <id>javadoc-xml</id>
+                        <goals>
+                            <goal>javadoc</goal>
+                        </goals>
+                        <configuration>
+                            <additionalOptions>
+                                <option>-docletpath</option>
+                                <option>${java.home}/../lib/tools.jar</option>
+                                <option>-doclet</option>
+                                <option>com.sun.tools.javadoc.Main</option>
+                                <option>-xml</option>
+                            </additionalOptions>
+                            <outputDirectory>target/site/apidocs</outputDirectory>
+                        </configuration>
+                    </execution>
                 </executions>
             </plugin>