Skip to content

Commit 6359fc5

Browse files
matreimatrei
committedJan 8, 2025
docs: convert from gdoc to asciidoc
GDoc is being deprecated.
1 parent c9f8fd0 commit 6359fc5

23 files changed

+542
-396
lines changed
 

‎build.gradle

+1
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ plugins {
33
id 'java-library'
44
id 'io.github.gradle-nexus.publish-plugin'
55
id 'maven-publish'
6+
id 'org.asciidoctor.jvm.convert' version '4.0.2'
67
id 'signing'
78
}
89

‎gradle/documentation-config.gradle

+39-10
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,10 @@
1-
import org.grails.gradle.plugin.doc.PublishGuideTask
2-
3-
apply plugin: 'org.grails.grails-doc'
4-
51
configurations.register('groovydocConfiguration')
62
configurations.register('guideConfiguration')
73

84
dependencies {
9-
105
add('groovydocConfiguration', localGroovy(), {
116
because 'groovydoc needs to run with the same version as Gradle'
127
})
13-
148
add('guideConfiguration', libs.grails.docs)
159
add('guideConfiguration', libs.groovy.templates)
1610
add('guideConfiguration', libs.slf4j.nop) // Get rid of logs during guide generation
@@ -25,8 +19,43 @@ tasks.withType(Groovydoc).configureEach {
2519
groovyClasspath = configurations.groovydocConfiguration
2620
}
2721

28-
tasks.withType(PublishGuideTask).configureEach {
29-
classpath = configurations.guideConfiguration
30-
javadocDir = null
31-
propertiesFile = layout.projectDirectory.file('src/docs/guide.properties').asFile
22+
asciidoctor {
23+
baseDir = file('src/docs')
24+
sourceDir = file('src/docs')
25+
outputDir = file('build/docs/manual')
26+
sources {
27+
include 'index.adoc'
28+
}
29+
jvm {
30+
jvmArgs += [
31+
'--add-opens', 'java.base/sun.nio.ch=ALL-UNNAMED',
32+
'--add-opens', 'java.base/java.io=ALL-UNNAMED'
33+
]
34+
}
35+
attributes = [
36+
copyright : 'Apache License, Version 2.0',
37+
docinfo1 : 'true',
38+
doctype : 'book',
39+
encoding : 'utf-8',
40+
icons : 'font',
41+
id : "$rootProject.name:$projectVersion",
42+
idprefix : '',
43+
idseparator : '-',
44+
lang : 'en',
45+
linkattrs : true,
46+
numbered : '',
47+
producer : 'Asciidoctor',
48+
revnumber : projectVersion,
49+
setanchors : true,
50+
'source-highlighter' : 'prettify',
51+
toc : 'left',
52+
toc2 : '',
53+
toclevels : '2',
54+
projectVersion : projectVersion
55+
]
56+
}
57+
58+
tasks.register('docs') {
59+
group = 'documentation'
60+
dependsOn 'asciidoctor', 'groovydoc'
3261
}

‎src/docs/1. Introduction.adoc

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
== Introduction
2+
3+
The Grails Mail Plugin provides a convenient DSL for _sending_ email. It supports plain-text, html, attachments, inline
4+
resources and i18n among other features.
5+
6+
Email can be sent using the `mailService` via the `sendMail` method.
7+
8+
Here is an example…
9+
10+
[source,groovy]
11+
----
12+
mailService.sendMail {
13+
to 'fred@gmail.com', 'ginger@gmail.com'
14+
from 'john@gmail.com'
15+
cc 'marge@gmail.com', 'ed@gmail.com'
16+
bcc 'joe@gmail.com'
17+
subject 'Hello John'
18+
text 'Here it some text'
19+
}
20+
----
21+
22+
Here we are sending a plain-text email with no attachments to the given addresses.
23+
24+
The `sendMail` method is injected into all Controllers to simplify access:
25+
26+
[source,groovy]
27+
----
28+
sendMail {
29+
to 'fred@g2one.com'
30+
subject 'Hello Fred'
31+
text 'How are you?'
32+
}
33+
----

‎src/docs/2.1 SMTP Server Configuration.adoc

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
=== SMTP Server Configuration
2+
3+
By default, the plugin assumes an unsecured mail server configured on port 25, getting the SMTP host name from the
4+
environment variable SMTP_HOST. However, you can change this via the `grails-app/conf/application.groovy` file.
5+
6+
Here is an example how you would configure the default sender to send with a Gmail account:
7+
8+
[source,groovy]
9+
----
10+
grails {
11+
mail {
12+
host = 'smtp.gmail.com'
13+
port = 465
14+
username = 'youracount@gmail.com'
15+
password = 'yourpassword'
16+
props = [
17+
'mail.smtp.auth': 'true',
18+
'mail.smtp.socketFactory.port': '465',
19+
'mail.smtp.socketFactory.class': 'javax.net.ssl.SSLSocketFactory',
20+
'mail.smtp.socketFactory.fallback': 'false'
21+
]
22+
}
23+
}
24+
----
25+
26+
And the configuration for sending via a Hotmail/Live account:
27+
28+
[source,groovy]
29+
----
30+
grails {
31+
mail {
32+
host = 'smtp.live.com'
33+
port = 587
34+
username = 'youracount@live.com'
35+
password = 'yourpassword'
36+
props = [
37+
'mail.smtp.starttls.enable': 'true',
38+
'mail.smtp.port': '587'
39+
]
40+
}
41+
}
42+
----
43+
44+
If your mail session is provided via JNDI, you can use the `jndiName` setting:
45+
46+
[source,groovy]
47+
----
48+
grails.mail.jndiName = 'myMailSession'
49+
----

‎src/docs/2.2 Defaults Configuration.adoc

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
=== Defaults Configuration
2+
3+
You can set various _default_ settings via the application configuration that will be used in the absence of explicit
4+
values when sending email.
5+
6+
You can also set the default "from" address to use for messages in `application.groovy` using:
7+
8+
[source,groovy]
9+
----
10+
grails.mail.default.from = 'server@yourhost.com'
11+
----
12+
13+
You can also set the default "to" address to use for messages in `application.groovy` using:
14+
15+
[source,groovy]
16+
----
17+
grails.mail.default.to = 'user@yourhost.com'
18+
----

‎src/docs/2.3 Other Configuration.adoc

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

‎src/docs/3. Sending Email.adoc

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
== Sending Emails
2+
3+
Email is sent using the `sendMail()` method of the `mailService`. This plugin also adds a shortcut `sendMail()` method
4+
to all Controllers and Services in your application that simply delegates to the `mailService`. There is no difference
5+
between the two methods so the choice is stylistic.
6+
7+
[source,groovy]
8+
----
9+
class PersonController {
10+
11+
def create = {
12+
// create user
13+
14+
sendMail {
15+
from 'admin@mysystem.com'
16+
subject 'New user'
17+
text 'A new user has been created'
18+
}
19+
}
20+
}
21+
----
22+
23+
[source,groovy]
24+
----
25+
class PersonController {
26+
27+
def mailService
28+
29+
def create = {
30+
// create user
31+
32+
mailService.sendMail {
33+
from 'admin@mysystem.com'
34+
subject 'New user'
35+
text 'A new user has been created'
36+
}
37+
}
38+
}
39+
----
40+
41+
The `sendMail()` method takes a single `Closure` argument that uses a DSL (Domain Specific Language) to configure the
42+
message to be sent. This section describes the aspects of the DSL.

‎src/docs/3.1 Sender And Recipient.adoc

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
=== Recipients
2+
3+
The DSL provides `to`, `cc` and `bcc` methods that allow you to set one or more address values for these recipient types.
4+
5+
[source,groovy]
6+
----
7+
sendMail {
8+
to 'someone@org.com'
9+
cc 'manager@org.com'
10+
bcc 'employee1@org.com', 'employee2@org.com'
11+
// ...
12+
}
13+
----
14+
15+
All methods take one or more String values that are email addresses using the syntax
16+
of http://www.ietf.org/rfc/rfc822.txt.[RFC822]. Typical address syntax is of the form `"user@host.domain"` or
17+
`"Personal Name <user@host.domain>"`.
18+
19+
You can supply multiple values for `to`, `cc` and `bcc`.
20+
21+
[source,groovy]
22+
----
23+
sendMail {
24+
to 'someone@org.com', 'someone.else@org.com'
25+
// …
26+
}
27+
----
28+
29+
If no value is provided for `to` when sending an email, the _default to-address_ will be used.
30+
31+
WARNING: If the configuration property `grails.mail.overrideAddress` is set, each recipient address specified will be
32+
substituted with the override address. See the configuration section for more information.
33+
34+
35+
=== Sender
36+
37+
The sender address of the email is configured with the `from` method.
38+
39+
[source,groovy]
40+
----
41+
sendMail {
42+
from 'me@org.com'
43+
// …
44+
}
45+
----
46+
47+
The `from` method accepts one String value email address using the syntax of
48+
https://www.ietf.org/rfc/rfc822.txt.[RFC822]. Typical address syntax is of the form `"user@host.domain"` or
49+
`"Personal Name <user@host.domain>"`.
50+
51+
If no value is provided for `from` when sending an email, the _default from-address_ will be used.

0 commit comments

Comments
 (0)