Merge pull request #64 from gpc/matrei/convert-docs

Convert Documentation from `gdoc` to `asciidoc`

.github/workflows/release-notes.yml

@@ -10,14 +10,18 @@ on:
     types: [opened, reopened, synchronize]
   pull_request_target:
     types: [opened, reopened, synchronize]
-  workflow_dispatch:
+
+permissions:
+  contents: read
+
 jobs:
   update_release_draft:
     permissions:
-      contents: read # limit to read access
+      contents: write
+      pull-requests: write
     runs-on: ubuntu-latest
     steps:
       - name: "📝 Update Release Draft"
         uses: release-drafter/release-drafter@v6
         env:
-          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

build.gradle

@@ -3,6 +3,7 @@ plugins {
     id 'java-library'
     id 'io.github.gradle-nexus.publish-plugin'
     id 'maven-publish'
+    id 'org.asciidoctor.jvm.convert' version '4.0.2'
     id 'signing'
 }
 

gradle/documentation-config.gradle

@@ -1,16 +1,10 @@
-import org.grails.gradle.plugin.doc.PublishGuideTask
-
-apply plugin: 'org.grails.grails-doc'
-
 configurations.register('groovydocConfiguration')
 configurations.register('guideConfiguration')
 
 dependencies {
-
     add('groovydocConfiguration', localGroovy(), {
         because 'groovydoc needs to run with the same version as Gradle'
     })
-
     add('guideConfiguration', libs.grails.docs)
     add('guideConfiguration', libs.groovy.templates)
     add('guideConfiguration', libs.slf4j.nop) // Get rid of logs during guide generation
@@ -25,8 +19,43 @@ tasks.withType(Groovydoc).configureEach {
     groovyClasspath = configurations.groovydocConfiguration
 }
 
-tasks.withType(PublishGuideTask).configureEach {
-    classpath = configurations.guideConfiguration
-    javadocDir = null
-    propertiesFile = layout.projectDirectory.file('src/docs/guide.properties').asFile
+asciidoctor {
+    baseDir = file('src/docs')
+    sourceDir = file('src/docs')
+    outputDir = file('build/docs/manual')
+    sources {
+        include 'index.adoc'
+    }
+    jvm {
+        jvmArgs += [
+            '--add-opens', 'java.base/sun.nio.ch=ALL-UNNAMED',
+            '--add-opens', 'java.base/java.io=ALL-UNNAMED'
+        ]
+    }
+    attributes = [
+        copyright            : 'Apache License, Version 2.0',
+        docinfo1             : 'true',
+        doctype              : 'book',
+        encoding             : 'utf-8',
+        icons                : 'font',
+        id                   : "$rootProject.name:$projectVersion",
+        idprefix             : '',
+        idseparator          : '-',
+        lang                 : 'en',
+        linkattrs            : true,
+        numbered             : '',
+        producer             : 'Asciidoctor',
+        revnumber            : projectVersion,
+        setanchors           : true,
+        'source-highlighter' : 'prettify',
+        toc                  : 'left',
+        toc2                 : '',
+        toclevels            : '2',
+        projectVersion       : projectVersion
+    ]
+}
+
+tasks.register('docs') {
+    group = 'documentation'
+    dependsOn 'asciidoctor', 'groovydoc'
 }

src/docs/1. Introduction.adoc

@@ -0,0 +1,33 @@
+== Introduction
+
+The Grails Mail Plugin provides a convenient DSL for _sending_ email. It supports plain-text, html, attachments, inline
+resources and i18n among other features.
+
+Email can be sent using the `mailService` via the `sendMail` method.
+
+Here is an example…
+
+[source,groovy]
+----
+mailService.sendMail {
+   to '[email protected]', '[email protected]'
+   from '[email protected]'
+   cc '[email protected]', '[email protected]'
+   bcc '[email protected]'
+   subject 'Hello John'
+   text 'Here it some text'
+}
+----
+
+Here we are sending a plain-text email with no attachments to the given addresses.
+
+The `sendMail` method is injected into all Controllers to simplify access:
+
+[source,groovy]
+----
+sendMail {
+   to '[email protected]'
+   subject 'Hello Fred'
+   text 'How are you?'
+}
+----

src/docs/2.1 SMTP Server Configuration.adoc

@@ -0,0 +1,49 @@
+=== SMTP Server Configuration
+
+By default, the plugin assumes an unsecured mail server configured on port 25, getting the SMTP host name from the
+environment variable SMTP_HOST. However, you can change this via the `grails-app/conf/application.groovy` file.
+
+Here is an example how you would configure the default sender to send with a Gmail account:
+
+[source,groovy]
+----
+grails {
+   mail {
+     host = 'smtp.gmail.com'
+     port = 465
+     username = '[email protected]'
+     password = 'yourpassword'
+     props = [
+        'mail.smtp.auth': 'true',
+        'mail.smtp.socketFactory.port': '465',
+        'mail.smtp.socketFactory.class': 'javax.net.ssl.SSLSocketFactory',
+        'mail.smtp.socketFactory.fallback': 'false'
+     ]
+  }
+}
+----
+
+And the configuration for sending via a Hotmail/Live account:
+
+[source,groovy]
+----
+grails {
+   mail {
+     host = 'smtp.live.com'
+     port = 587
+     username = '[email protected]'
+     password = 'yourpassword'
+     props = [
+        'mail.smtp.starttls.enable': 'true',
+        'mail.smtp.port': '587'
+     ]
+  }
+}
+----
+
+If your mail session is provided via JNDI, you can use the `jndiName` setting:
+
+[source,groovy]
+----
+grails.mail.jndiName = 'myMailSession'
+----

src/docs/2.2 Defaults Configuration.adoc

@@ -0,0 +1,18 @@
+=== Defaults Configuration
+
+You can set various _default_ settings via the application configuration that will be used in the absence of explicit
+values when sending email.
+
+You can also set the default "from" address to use for messages in `application.groovy` using:
+
+[source,groovy]
+----
+grails.mail.default.from = '[email protected]'
+----
+
+You can also set the default "to" address to use for messages in `application.groovy` using:
+
+[source,groovy]
+----
+grails.mail.default.to = '[email protected]'
+----

src/docs/2.3 Other Configuration.adoc

@@ -0,0 +1,27 @@
+=== Disabling Email Sending
+
+You can completely disable the sending of email by setting:
+
+[source,groovy]
+----
+grails.mail.disabled = true
+----
+
+You may want to set this value for the development and/or test environments. However, this will treat any call to
+`mailService.sendMail()` as a no-op which means that the mail plugin will not attempt to render the email message or
+assemble any attachments. This can hide issues such as incorrect view names, invalid or non-existent configuration
+during development.
+
+Consider using the https://github.com/gpc/greenmail[Greenmail Plugin] which allows you to start an in memory test SMTP
+server for local development. This allows you to test more of your code.
+
+=== Overriding Addresses
+
+An alternative to disabling email or using something like the http://www.grails.org/plugin/greenmail[Greenmail Plugin]
+, is to use the `overrideAddress` config setting for your development and/or test environment to force all email to be
+delivered to a specific address, regardless of what the addresses were at send time:
+
+[source,groovy]
+----
+grails.mail.overrideAddress = '[email protected]'
+----

src/docs/3. Sending Email.adoc

@@ -0,0 +1,42 @@
+== Sending Emails
+
+Email is sent using the `sendMail()` method of the `mailService`. This plugin also adds a shortcut `sendMail()` method
+to all Controllers and Services in your application that simply delegates to the `mailService`. There is no difference
+between the two methods so the choice is stylistic.
+
+[source,groovy]
+----
+class PersonController {
+
+    def create = {
+        // create user
+
+        sendMail {
+            from '[email protected]'
+            subject 'New user'
+            text 'A new user has been created'
+        }
+    }
+}
+----
+
+[source,groovy]
+----
+class PersonController {
+
+    def mailService
+
+    def create = {
+        // create user
+
+        mailService.sendMail {
+            from '[email protected]'
+            subject 'New user'
+            text 'A new user has been created'
+        }
+    }
+}
+----
+
+The `sendMail()` method takes a single `Closure` argument that uses a DSL (Domain Specific Language) to configure the
+message to be sent. This section describes the aspects of the DSL.

src/docs/3.1 Sender And Recipient.adoc

@@ -0,0 +1,51 @@
+=== Recipients
+
+The DSL provides `to`, `cc` and `bcc` methods that allow you to set one or more address values for these recipient types.
+
+[source,groovy]
+----
+sendMail {
+    to '[email protected]'
+    cc '[email protected]'
+    bcc '[email protected]', '[email protected]'
+    // ...
+}
+----
+
+All methods take one or more String values that are email addresses using the syntax
+of http://www.ietf.org/rfc/rfc822.txt.[RFC822]. Typical address syntax is of the form `"[email protected]"` or
+`"Personal Name <[email protected]>"`.
+
+You can supply multiple values for `to`, `cc` and `bcc`.
+
+[source,groovy]
+----
+sendMail {
+    to '[email protected]', '[email protected]'
+    // …
+}
+----
+
+If no value is provided for `to` when sending an email, the _default to-address_ will be used.
+
+WARNING: If the configuration property `grails.mail.overrideAddress` is set, each recipient address specified will be
+substituted with the override address. See the configuration section for more information.
+
+
+=== Sender
+
+The sender address of the email is configured with the `from` method.
+
+[source,groovy]
+----
+sendMail {
+    from '[email protected]'
+    // …
+}
+----
+
+The `from` method accepts one String value email address using the syntax of
+https://www.ietf.org/rfc/rfc822.txt.[RFC822]. Typical address syntax is of the form `"[email protected]"` or
+`"Personal Name <[email protected]>"`.
+
+If no value is provided for `from` when sending an email, the _default from-address_ will be used.