Merge pull request #7 from teogor/docs/populate-content

Document 1.0.0-alpha01 Release Notes and Enhance Documentation Site

.github/workflows/publish-docs.yml

@@ -27,8 +27,9 @@ env:
 
 jobs:
   synchronize-documentation:
+    environment: PRODUCTION
     runs-on: ubuntu-latest
-    name: Synchronize Repository API Documentation
+    name: Synchronize Repository Documentation
     steps:
       - uses: actions/checkout@v4
 
@@ -44,10 +45,13 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install mkdocs mkdocs-material
+          pip install mkdocs-material
+          pip install mkdocs-material[recommended,git,imaging]
 
       - name: Build MkDocs
-        run: mkdocs build
+        run: |
+          mkdocs build --clean
+          mkdocs --version
 
       - name: Setup Java
         uses: actions/setup-java@v3
@@ -58,13 +62,13 @@ jobs:
       - name: Generate API Documentation
         run: ./gradlew -D'org.gradle.unsafe.configuration-cache=false' dokkaHtmlMultiModule
 
-      - name: Relocate API Documentation Assets
+      - name: Relocate API References
         run: |
-          mkdir -p build/docs/${{ env.REPOSITORY }}/documentation
-          cp -r build/dokka/htmlMultiModule/* build/docs/${{ env.REPOSITORY }}/documentation
+          mkdir -p build/docs/${{ env.REPOSITORY }}/html
+          cp -r build/dokka/htmlMultiModule/* build/docs/${{ env.REPOSITORY }}/html
 
       - id: publish-docs
-        name: Deploy API Documentation
+        name: Deploy Documentation
         uses: ./.github/workflows/sync-docs/
         env:
           API_TOKEN_GITHUB: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
@@ -77,6 +81,7 @@ jobs:
           destination-branch-create: ${{ env.DESTINATION_BRANCH }}
 
   build-and-deploy:
+    environment: PRODUCTION
     needs: synchronize-documentation
     name: Build and Deploy Updated API Documentation
     runs-on: ubuntu-latest
@@ -90,13 +95,13 @@ jobs:
           # This is important to fetch the changes to the previous commit
           fetch-depth: 0
 
-      - name: Prettify code
-        uses: creyD/prettier_action@v4.3
-        with:
-          # This part is also where you can pass other options, for example:
-          prettier_options: --write ${{ env.REPOSITORY }}/**/*.{js,html,css,json}
-          only_changed: False
-          same_commit: True
+#      - name: Prettify code
+#        uses: creyD/prettier_action@v4.3
+#        with:
+#          # This part is also where you can pass other options, for example:
+#          prettier_options: --write ${{ env.REPOSITORY }}/**/*.{js,html,css,json}
+#          only_changed: False
+#          same_commit: True
 
       - name: Create PR (Pull Request)
         run: |

.github/workflows/publish.yml

@@ -1,23 +1,21 @@
 name: Publish
 
 on:
+  release:
+    types: [ released ]
   workflow_dispatch:
 
 jobs:
   publish:
     name: Snapshot build and publish
     runs-on: ubuntu-latest
     environment: PRODUCTION
-    timeout-minutes: 120
     env:
       ORG_GRADLE_PROJECT_mavenCentralUsername: ${{ secrets.OSSRH_USERNAME }}
       ORG_GRADLE_PROJECT_mavenCentralPassword: ${{ secrets.OSSRH_PASSWORD }}
       ORG_GRADLE_PROJECT_signingInMemoryKeyId: ${{ secrets.SIGNING_KEY_ID }}
       ORG_GRADLE_PROJECT_signingInMemoryKeyPassword: ${{ secrets.SIGNING_PASSWORD }}
       ORG_GRADLE_PROJECT_signingInMemoryKey: ${{ secrets.SIGNING_KEY }}
-      SONATYPE_CONNECT_TIMEOUT_SECONDS: 120
-      SONATYPE_CLOSE_TIMEOUT_SECONDS: 1800
-
     steps:
       - name: Check out code
         uses: actions/checkout@v3.1.0
@@ -31,6 +29,6 @@ jobs:
       - name: Grant Permission to Execute Gradle
         run: chmod +x gradlew
 
-      - name: Publish to Maven Central
+      - name: Publish to MavenCentral
         run: |
           ./gradlew :api:publish --no-configuration-cache

.gitignore

@@ -19,3 +19,5 @@ gradle-app.setting
 .project
 # JDT-specific (Eclipse Java Development Tools)
 .classpath
+
+.idea

docs/api-documentation.md → docs/reference.md

@@ -1,4 +1,4 @@
-## API Documentation
+## Reference
 
 Welcome to the comprehensive API documentation for our project, meticulously crafted to empower you to
 effectively utilize its capabilities. This guide provides detailed information about the project's
@@ -10,13 +10,11 @@ Our project encompasses a suite of modules, each designed to address specific fu
 the overall developer experience. To delve into the intricacies of each module, refer to the dedicated
 documentation pages:
 
-- **[Querent 🔗](../documentation):** Discover the heart of our project.
+### API Reference
 
-- **[API 🔗](../documentation/api):** Navigate directly to the code-specific documentation for the project's
-`:api` module
-
-- **[Plugin 🔗](../documentation/gradle-plugin):** Navigate directly to the code-specific documentation for
-the project's `:gradle-plugin` module
+* [`dev.teogor.querent`](../html/){:target="_blank"}
+* [`dev.teogor.querent:api`](../html/api){:target="_blank"}
+* [`dev.teogor.querent:gradle-plugin`](../html/gradle-plugin){:target="_blank"}
 
 ### Contributions and Support
 

docs/releases.md

@@ -0,0 +1,81 @@
+[//]: # (This file was automatically generated - do not edit)
+
+# Querent
+
+Querent is a versatile and intuitive Sudoku puzzle generation library written in Kotlin. It
+provides a comprehensive set of tools and algorithms for generating Sudoku puzzles of various grid
+sizes and difficulty levels.
+
+---
+
+### API Reference
+
+* [`dev.teogor.querent`](../html/){:target="_blank"}
+* [`dev.teogor.querent:api`](../html/api){:target="_blank"}
+* [`dev.teogor.querent:gradle-plugin`](../html/gradle-plugin){:target="_blank"}
+
+### Release
+
+|   Latest Update   | Stable Release | Beta Release | Alpha Release |
+|:-----------------:|:--------------:|:------------:|:-------------:|
+| November 27, 2023 |       -        |      -       | 1.0.0-alpha01 |
+
+### Declaring dependencies
+
+To add a dependency on Querent, you must add the Maven repository to your project.
+Read [Maven's repository for more information](https://repo.maven.apache.org/maven2/).
+
+Add the dependencies for the artifacts you need in the `build.gradle` file for your app or module:
+
+=== "Kotlin"
+
+    ```kotlin
+    plugins {
+      id("dev.teogor.querent") version "1.0.0-alpha01"
+    }
+
+    repositories {
+      mavenCentral() // Add the repository where the library is hosted
+    }
+
+    dependencies {
+      implementation("dev.teogor.querent:querent-api:1.0.0-alpha01")
+    }
+    ```
+
+=== "Groovy"
+
+    ```groovy
+    plugins {
+      id 'dev.teogor.querent' version '1.0.0-alpha01'
+    }
+
+    repositories {
+      mavenCentral() // Add the repository where the library is hosted
+    }
+
+    dependencies {
+      implementation 'dev.teogor.querent:querent-api:1.0.0-alpha01'
+    }
+    ```
+
+### Feedback
+
+Your feedback helps make Querent better. We want to know if you discover new issues or have ideas
+for improving this library. Before creating a new issue, please take a look at
+the [existing ones](https://github.com/teogor/querent) in this library. You can add your vote to
+an
+existing issue by clicking the star button.
+
+[Create a new issue](https://github.com/teogor/querent/issues/new){ .md-button }
+
+### Version 1.0.0
+
+#### Version 1.0.0-alpha01
+
+November 27, 2023
+
+`dev.teogor.querent:querent-*:1.0.0-alpha01` is
+released. [Version 1.0.0-alpha01 contains these commits.](https://github.com/teogor/querent/commits/1.0.0-alpha01)
+
+**Initial Release** 🎊

docs/releases/changelog/1.0.0-alpha01.md

@@ -0,0 +1,10 @@
+[//]: # (This file was automatically generated - do not edit)
+
+# Version 1.0.0-alpha01
+
+## Latest SDK versions
+
+| Status |                           Service or Product                           |       Gradle dependency        | Latest version |
+|:------:|:----------------------------------------------------------------------:|:------------------------------:|:--------------:|
+|   🧪   | [Querent Gradle Plugin](../../../html/gradle-plugin){:target="_blank"} |       dev.teogor.querent       | 1.0.0-alpha01  |
+|   🧪   |    [Querent Gradle PLugin API](../../../html/api){:target="_blank"}    | dev.teogor.querent:querent-api | 1.0.0-alpha01  |

docs/releases/implementation.md

@@ -0,0 +1,61 @@
+[//]: # (This file was automatically generated - do not edit)
+
+## Implementation
+
+### Latest Version
+
+The latest release is [`1.0.0-alpha01`](../releases.md)
+
+### Releases
+
+Here's a summary of the latest versions:
+
+|    Version    |               Release Notes                | Release Date |
+|:-------------:|:------------------------------------------:|:------------:|
+| 1.0.0-alpha01 | [changelog 🔗](changelog/1.0.0-alpha01.md) | 27 Nov 2023  |
+
+### Using Version Catalog
+
+#### Declare Components
+
+This catalog provides the implementation details of Querent libraries, including and individual
+libraries, in TOML format.
+
+=== "Default"
+
+    ```toml title="gradle/libs.versions.toml"
+    [versions]
+    teogor-querent = "1.0.0-alpha01"
+
+    [libraries]
+    teogor-querent-api = { module = "dev.teogor.querent:querent-api", version.ref = "teogor-querent" }
+
+    [plugins]
+    teogor-querent = { id = "dev.teogor.querent", version.ref = "teogor-querent" }
+    ```
+
+#### Dependencies Implementation
+
+=== "Kotlin"
+
+    ```kotlin title="build.gradle.kts"
+    plugins {
+      alias(libs.plugins.teogor.querent)
+    }
+
+    dependencies {
+      // Option - Not Required
+      implementation(libs.teogor.querent.api)
+    }
+    ```
+
+=== "Groovy"
+
+    ```groovy title="build.gradle"
+    apply plugin: libs.plugins.teogor.querent
+
+    dependencies {
+      // Option - Not Required
+      implementation libs.teogor.querent.api
+    }
+    ```

docs/security.md

@@ -5,12 +5,11 @@
 Please refer to this table to see which versions of the project are currently receiving security
 updates:
 
-| Version | Supported          |
-|---------|--------------------|
-| Release | ✅                 |
-| ALPHA   | ❌                 |
-| BETA    | ❌                 |
-
+| Version | Supported |
+|:-------:|:---------:|
+| STABLE  |     ✅     |
+|  ALPHA  |     ❌     |
+|  BETA   |     ❌     |
 
 ## Reporting a Vulnerability
 
@@ -21,7 +20,8 @@ If you discover a security vulnerability within this project, please follow thes
 
 2. **Contact Us:** Report the vulnerability to us by sending an email
    to [open-source@teogor.dev](mailto:open-source@teogor.dev). You can encrypt sensitive information
-   using our [PGP key](https://source.teogor.dev/security/pgp-key) to ensure the confidentiality of the report.
+   using our [PGP key](https://source.teogor.dev/security/pgp-key) to ensure the confidentiality of
+   the report.
 
 3. **Provide Details:** Please provide us with detailed information about the vulnerability,
    including steps to reproduce, affected versions, and potential impact.