From 960fa69edd4294328e8139eaec56e8f7ca899e82 Mon Sep 17 00:00:00 2001
From: vtasun <tasun.v.s@gmail.com>
Date: Mon, 11 Nov 2024 01:36:25 +0200
Subject: [PATCH 1/3] Added DocFX to create API References site

---
 .github/workflows/javadoc-publish.yml | 22 +++++---
 docs/docfx.json                       | 15 ++++++
 docs/getting-started.md               | 76 +++++++++++++++++++++++++++
 docs/index.md                         | 18 +++++++
 docs/javadocs.md                      |  3 ++
 docs/toc.yml                          |  8 +++
 docs/usage-examples.md                |  3 ++
 pom.xml                               | 16 ++++++
 8 files changed, 154 insertions(+), 7 deletions(-)
 create mode 100644 docs/docfx.json
 create mode 100644 docs/getting-started.md
 create mode 100644 docs/index.md
 create mode 100644 docs/javadocs.md
 create mode 100644 docs/toc.yml
 create mode 100644 docs/usage-examples.md

diff --git a/.github/workflows/javadoc-publish.yml b/.github/workflows/javadoc-publish.yml
index e283dc3..7d0fb5c 100644
--- a/.github/workflows/javadoc-publish.yml
+++ b/.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,25 @@ jobs:
           java-version: 17
           distribution: 'temurin'
 
+      - name: Install .NET SDK (required for DocFX as a .NET tool)
+        uses: actions/setup-dotnet@v3
+        with:
+          dotnet-version: '7.x'
+
+      - 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
 
-      # Upload the Javadocs as an artifact to be deployed
-      - name: Upload Javadocs Artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: target/reports/apidocs
+      - name: Build Documentation Site
+        run: docfx ./docs/docfx.json
+
+      - name: Copy Javadocs to _site/api-docs
+        run: cp -r target/reports/apidocs/* docs/_site/java-docs/
 
   deploy:
-    name: Deploy Javadocs to GitHub Pages
+    name: Deploy to GitHub Pages
 
     runs-on: ubuntu-latest
     needs: build
diff --git a/docs/docfx.json b/docs/docfx.json
new file mode 100644
index 0000000..f07a2a2
--- /dev/null
+++ b/docs/docfx.json
@@ -0,0 +1,15 @@
+{
+  "build": {
+    "content": [
+      {
+        "files": ["*.md", "**.md", "toc.yml"]
+      }
+    ],
+    "resource": [
+      {
+        "files": ["images*"]
+      }
+    ],
+    "dest": "_site"
+  }
+}
\ No newline at end of file
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 0000000..bcbb7a0
--- /dev/null
+++ b/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 = "sender@domain.com";
+    private static final String RECIPIENT_EMAIL = "recipient@domain.com";
+
+    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);
+        }
+    }
+}
+```
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..47fa836
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,18 @@
+---
+_layout: landing
+---
+# Official Mailtrap Java Client
+
+Welcome to the documentation portal for official Java client for <a href="https://mailtrap.io/" target="_blank">Mailtrap</a>!
+
+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>.
\ No newline at end of file
diff --git a/docs/javadocs.md b/docs/javadocs.md
new file mode 100644
index 0000000..b59c986
--- /dev/null
+++ b/docs/javadocs.md
@@ -0,0 +1,3 @@
+# Detailed Java API Reference
+
+View the <a href="./java-docs/index.html" target="_blank">Java API Documentation</a>.
diff --git a/docs/toc.yml b/docs/toc.yml
new file mode 100644
index 0000000..d39d59d
--- /dev/null
+++ b/docs/toc.yml
@@ -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
\ No newline at end of file
diff --git a/docs/usage-examples.md b/docs/usage-examples.md
new file mode 100644
index 0000000..2b60abf
--- /dev/null
+++ b/docs/usage-examples.md
@@ -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>
\ No newline at end of file
diff --git a/pom.xml b/pom.xml
index be10c15..a3f29fc 100644
--- a/pom.xml
+++ b/pom.xml
@@ -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>
 

From ec45ea0624cdc39670fc4b2fe0e33b2c05a240b2 Mon Sep 17 00:00:00 2001
From: vtasun <tasun.v.s@gmail.com>
Date: Tue, 12 Nov 2024 01:39:58 +0200
Subject: [PATCH 2/3] DocFX site updates - added custom logo, minor texts
 changes

---
 .github/workflows/javadoc-publish.yml |   4 ++--
 docs/docfx.json                       |   5 ++++-
 docs/images/logo.png                  | Bin 0 -> 3597 bytes
 docs/index.md                         |   2 +-
 4 files changed, 7 insertions(+), 4 deletions(-)
 create mode 100644 docs/images/logo.png

diff --git a/.github/workflows/javadoc-publish.yml b/.github/workflows/javadoc-publish.yml
index 7d0fb5c..ef330fd 100644
--- a/.github/workflows/javadoc-publish.yml
+++ b/.github/workflows/javadoc-publish.yml
@@ -21,7 +21,7 @@ jobs:
           java-version: 17
           distribution: 'temurin'
 
-      - name: Install .NET SDK (required for DocFX as a .NET tool)
+      - name: Install .NET SDK # required for DocFX as a .NET tool
         uses: actions/setup-dotnet@v3
         with:
           dotnet-version: '7.x'
@@ -36,7 +36,7 @@ jobs:
         run: docfx ./docs/docfx.json
 
       - name: Copy Javadocs to _site/api-docs
-        run: cp -r target/reports/apidocs/* docs/_site/java-docs/
+        run: mv -r target/reports/apidocs/* docs/_site/java-docs/
 
   deploy:
     name: Deploy to GitHub Pages
diff --git a/docs/docfx.json b/docs/docfx.json
index f07a2a2..046e561 100644
--- a/docs/docfx.json
+++ b/docs/docfx.json
@@ -1,5 +1,8 @@
 {
   "build": {
+    "globalMetadata": {
+      "_appLogoPath": "images/logo.png"
+    },
     "content": [
       {
         "files": ["*.md", "**.md", "toc.yml"]
@@ -7,7 +10,7 @@
     ],
     "resource": [
       {
-        "files": ["images*"]
+        "files": ["images/*"]
       }
     ],
     "dest": "_site"
diff --git a/docs/images/logo.png b/docs/images/logo.png
new file mode 100644
index 0000000000000000000000000000000000000000..82dbe295d9e38f08f25f3f78f0a4f645250edab5
GIT binary patch
literal 3597
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
TZkbL{00000NkvXXu0mjfA1l^~

literal 0
HcmV?d00001

diff --git a/docs/index.md b/docs/index.md
index 47fa836..e0d0f6d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,7 +3,7 @@ _layout: landing
 ---
 # Official Mailtrap Java Client
 
-Welcome to the documentation portal for official Java client for <a href="https://mailtrap.io/" target="_blank">Mailtrap</a>!
+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.
 

From eec9ee2b597d47b7f65ee1ec62fdf2babd5a7023 Mon Sep 17 00:00:00 2001
From: vtasun <tasun.v.s@gmail.com>
Date: Fri, 15 Nov 2024 00:12:40 +0200
Subject: [PATCH 3/3] Minor workflow file updates

---
 .github/workflows/javadoc-publish.yml | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/javadoc-publish.yml b/.github/workflows/javadoc-publish.yml
index ef330fd..6283d07 100644
--- a/.github/workflows/javadoc-publish.yml
+++ b/.github/workflows/javadoc-publish.yml
@@ -22,9 +22,7 @@ jobs:
           distribution: 'temurin'
 
       - name: Install .NET SDK # required for DocFX as a .NET tool
-        uses: actions/setup-dotnet@v3
-        with:
-          dotnet-version: '7.x'
+        uses: actions/setup-dotnet@v4
 
       - name: Install DocFX Tool
         run: dotnet tool install -g docfx
@@ -36,7 +34,15 @@ jobs:
         run: docfx ./docs/docfx.json
 
       - name: Copy Javadocs to _site/api-docs
-        run: mv -r target/reports/apidocs/* docs/_site/java-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 Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_site
 
   deploy:
     name: Deploy to GitHub Pages