Documentation: Cleanup Title Sequence

[jamesfredley]

Issue description

Run ./gradlew assemble

Review and correct error like the following:

WARNING: eventsAutoTimestamping.adoc: line 36: section title out of sequence: expected level 1, got level 3
WARNING: eventsAutoTimestamping.adoc: line 174: section title out of sequence: expected level 1, got level 3
WARNING: eventsAutoTimestamping.adoc: line 91: section title out of sequence: expected level 1, got level 3
WARNING: eventsAutoTimestamping.adoc: line 114: section title out of sequence: expected level 1, got level 3
WARNING: configurationDefaults.adoc: line 22: section title out of sequence: expected level 1, got level 3

[dauer]

The issue is that the documentation is assembled from multiple documents.

The root document index.adoc includes multiple other documents fx. advancedGORMFeatures/eventsAutoTimestamping.adoc
When the included documents are processed individually Asciidoctor complains about the headlines starting from level 3 (which is where the root document expects them).

Solution 1
I think a solution is to write the documents as if they where not to be inserted in the root document (treat them as individual docs), meaning headlines starts from level 1.
When inserted into the root document (index.adoc) we then adjust the level offset:
include::advancedGORMFeatures/eventsAutoTimestamping.adoc[leveloffset=+2]

https://docs.asciidoctor.org/asciidoc/latest/directives/include-with-leveloffset/

The drawback is that it requires some editing, there are a lot of *.adoc files...

Solution 2
Or if we don't want to generate the files in the sub folders, prefix those documents and folders with an underscore _ which will exclude them unless they are included from other files.

[jamesfredley]

Solution 1 is the selected direction

[jamesfredley]

Here is a current example of a slightly different take on Solution 1.

grails-core/grails-doc/src/en/guide/index.adoc

Lines 268 to 277 in 0c944d3

	[[profiles]]
	== Application Profiles
	include::profiles.adoc[]
	[[creatingProfiles]]
	=== Creating Profiles
	include::profiles/creatingProfiles.adoc[]

grails-core/grails-doc/src/en/guide/profiles/creatingProfiles.adoc

Lines 19 to 53 in 1d49052

	The idea behind creating a new profile is that you can setup a default set of commands and plugins that are tailored to a particular technology or organisation.
	To create a new profile you can use the link:../ref/Command%20Line/create-profile.html[create-profile] command which will create a new empty profile that extends the base profile:
	[source,bash]
	----
	$ grails create-profile mycompany
	----
	The above command will create a new profile in the "mycompany" directory where the command is executed. If you start interactive mode within the directory you will get a set of commands for creating profiles:
	[source,bash]
	----
	$ cd mycompany
	$ grails
	| Enter a command name to run. Use TAB for completion:
	grails>
	create-command create-creator-command create-feature create-generator-command create-gradle-command create-template
	----
	The commands are as follows:
	* `create-command` - creates a new command that will be available from the Grails CLI when the profile is used
	* `create-creator-command` - creates a command available to the CLI that renders a template (Example: create-controller)
	* `create-generator-command` - creates a command available to the CLI that renders a template based on a domain class (Example: generate-controller)
	* `create-feature` - creates a feature that can be used with this profile
	* `create-gradle-command` - creates a CLI command that can invoke gradle
	* `create-template` - creates a template that can be rendered by a command
	To customize the dependencies for your profile you can specify additional dependencies in `profile.yml`.
	Below is an example `profile.yml` file: