Fix: correctly resolve all documentation title sequence warnings using leveloffset and fragments with level 0 headers

Author: sanjana2505006

grails-data-hibernate5/docs/src/docs/asciidoc/advancedGORMFeatures/eventsAutoTimestamping.adoc

@@ -17,6 +17,8 @@ specific language governing permissions and limitations
 under the License.
 ////
 
+= Events and Auto Timestamping
+
 GORM supports the registration of events as methods that get fired when certain events occurs such as deletes, inserts and updates. The following is a list of supported events:
 
 * `beforeInsert` - Executed before an object is initially persisted to the database.  If you return false, the insert will be cancelled.
@@ -33,7 +35,7 @@ To add an event simply register the relevant method with your domain class.
 WARNING: Do not attempt to flush the session within an event (such as with obj.save(flush:true)). Since events are fired during flushing this will cause a StackOverflowError.
 
 
-==== The beforeInsert event
+== The beforeInsert event
 
 
 Fired before an object is saved to the database
@@ -56,7 +58,7 @@ class Person {
 ----
 
 
-==== The beforeUpdate event
+== The beforeUpdate event
 
 
 Fired before an existing object is updated
@@ -88,7 +90,7 @@ class Person {
 Notice the usage of `autowire true` above. This is required for the bean `securityService` to be injected.
 
 
-==== The beforeDelete event
+== The beforeDelete event
 
 
 Fired before an object is deleted.
@@ -111,7 +113,7 @@ Notice the usage of `withNewSession` method above. Since events are triggered wh
 Fortunately the `withNewSession` method lets you share the same transactional JDBC connection even though you're using a different underlying `Session`.
 
 
-==== The beforeValidate event
+== The beforeValidate event
 
 
 Fired before an object is validated.
@@ -171,7 +173,7 @@ no-arg version if no arguments are passed to `validate` but will fall back on th
 `List` version if the no-arg version does not exist.  In that case, `null` is passed to `beforeValidate`.
 
 
-==== The onLoad/beforeLoad event
+== The onLoad/beforeLoad event
 
 
 Fired immediately before an object is loaded from the database:
@@ -192,7 +194,7 @@ class Person {
 `beforeLoad()` is effectively a synonym for `onLoad()`, so only declare one or the other.
 
 
-==== The afterLoad event
+== The afterLoad event
 
 
 Fired immediately after an object is loaded from the database:
@@ -211,7 +213,7 @@ class Person {
 ----
 
 
-==== Custom Event Listeners
+== Custom Event Listeners
 
 To register a custom event listener you need to subclass `AbstractPersistenceEventListener` (in package _org.grails.datastore.mapping.engine.event_) and implement the methods `onPersistenceEvent` and `supportsEventType`. You also must provide a reference to the datastore to the listener.  The simplest possible implementation can be seen below:
 
@@ -277,7 +279,7 @@ datastore.getApplicationEventPublisher()
 ----
 
 
-==== Hibernate Events
+== Hibernate Events
 
 
 It is generally encouraged to use the non-Hibernate specific API described above, but if you need access to more detailed Hibernate events then you can define custom Hibernate-specific event listeners.
@@ -359,7 +361,7 @@ def doWithSpring = {
 ----
 
 
-==== Automatic timestamping
+== Automatic timestamping
 
 
 If you define a `dateCreated` property it will be set to the current date for you when you create new instances. Likewise, if you define a `lastUpdated` property it will be automatically be updated for you when you change persistent instances.

grails-data-hibernate5/docs/src/docs/asciidoc/index.adoc

@@ -190,9 +190,7 @@ include::querying/hql.adoc[]
 include::advancedGORMFeatures.adoc[]
 
 [[eventsAutoTimestamping]]
-=== Events and Auto Timestamping
-
-include::advancedGORMFeatures/eventsAutoTimestamping.adoc[]
+include::advancedGORMFeatures/eventsAutoTimestamping.adoc[leveloffset=+2]
 
 [[ormdsl]]
 === Custom ORM Mapping
@@ -265,9 +263,7 @@ include::advancedGORMFeatures/ormdsl/customNamingStrategy.adoc[]
 include::advancedGORMFeatures/defaultSortOrder.adoc[]
 
 [[programmaticTransactions]]
-== Programmatic Transactions
-
-include::programmaticTransactions.adoc[]
+include::programmaticTransactions.adoc[leveloffset=+1]
 
 [[dataServices]]
 == GORM Data Services

grails-data-hibernate5/docs/src/docs/asciidoc/programmaticTransactions.adoc

@@ -17,11 +17,13 @@ specific language governing permissions and limitations
 under the License.
 ////
 
+= Programmatic Transactions
+
 GORM's transaction management is built on Spring and uses Spring's Transaction abstraction for dealing with programmatic transactions.
 
 However, GORM classes have been enhanced to make this simpler with the link:../api/org/grails/datastore/gorm/GormEntity.html#withTransaction(groovy.lang.Closure)[withTransaction(Closure)]  method. This method has a single parameter, a Closure, which has a single parameter which is a Spring https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/transaction/TransactionStatus.html[TransactionStatus] instance.
 
-==== Using the withTransaction Method
+== Using the withTransaction Method
 
 Here's an example of using `withTransaction` in a controller methods:
 
@@ -56,7 +58,7 @@ You can also use "save points" to rollback a transaction to a particular point i
 
 The `withTransaction` method deals with the begin/commit/rollback logic for you within the scope of the block.
 
-==== Using TransactionService
+== Using TransactionService
 
 Since GORM 6.1, if you need more flexibility then instead you can instead take advantage of the link:../api/grails/gorm/transactions/TransactionService.html[TransactionService], which can be obtained by looking it up from from the `HibernateDatastore`:
 

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

@@ -1075,44 +1075,30 @@ include::plugins.adoc[]
 include::plugins/creatingAndInstallingPlugins.adoc[leveloffset=+2]
 
 [[repositories]]
-=== Plugin Repositories
-
-include::plugins/repositories.adoc[]
+include::plugins/repositories.adoc[leveloffset=+2]
 
 [[providingBasicArtefacts]]
-=== Providing Basic Artefacts
-
-include::plugins/providingBasicArtefacts.adoc[]
+include::plugins/providingBasicArtefacts.adoc[leveloffset=+2]
 
 [[evaluatingConventions]]
 === Evaluating Conventions
 
 include::plugins/evaluatingConventions.adoc[]
 
 [[hookingIntoRuntimeConfiguration]]
-=== Hooking into Runtime Configuration
-
-include::plugins/hookingIntoRuntimeConfiguration.adoc[]
+include::plugins/hookingIntoRuntimeConfiguration.adoc[leveloffset=+2]
 
 [[addingMethodsAtCompileTime]]
-=== Adding Methods at Compile Time
-
-include::plugins/addingMethodsAtCompileTime.adoc[]
+include::plugins/addingMethodsAtCompileTime.adoc[leveloffset=+2]
 
 [[addingDynamicMethodsAtRuntime]]
-=== Adding Dynamic Methods at Runtime
-
-include::plugins/addingDynamicMethodsAtRuntime.adoc[]
+include::plugins/addingDynamicMethodsAtRuntime.adoc[leveloffset=+2]
 
 [[participatingInAutoReloadEvents]]
-=== Participating in Auto Reload Events
-
-include::plugins/participatingInAutoReloadEvents.adoc[]
+include::plugins/participatingInAutoReloadEvents.adoc[leveloffset=+2]
 
 [[understandingPluginLoadOrder]]
-=== Understanding Plugin Load Order
-
-include::plugins/understandingPluginLoadOrder.adoc[]
+include::plugins/understandingPluginLoadOrder.adoc[leveloffset=+2]
 
 [[artefactApi]]
 === The Artefact API

grails-doc/src/en/guide/plugins/addingDynamicMethodsAtRuntime.adoc

@@ -17,8 +17,10 @@ specific language governing permissions and limitations
 under the License.
 ////
 
+= Adding Dynamic Methods at Runtime
 
-==== The Basics
+
+== The Basics
 
 
 Grails plugins let you register dynamic methods with any Grails-managed or other class at runtime. This work is done in a `doWithDynamicMethods` method.
@@ -62,7 +64,7 @@ class ExamplePlugin extends Plugin  {
 ----
 
 
-==== Interacting with the ApplicationContext
+== Interacting with the ApplicationContext
 
 
 The `doWithDynamicMethods` closure gets passed the Spring `ApplicationContext` instance. This is useful as it lets you interact with objects within it. For example if you were implementing a method to interact with Hibernate you could use the `SessionFactory` instance in combination with a `HibernateTemplate`:

grails-doc/src/en/guide/plugins/addingMethodsAtCompileTime.adoc

@@ -17,6 +17,8 @@ specific language governing permissions and limitations
 under the License.
 ////
 
+= Adding Methods at Compile Time
+
 Grails makes it easy to add new traits to existing artefact types from a plugin. For example say you wanted to add methods for manipulating dates to controllers. This can be done by defining a trait in `src/main/groovy`:
 
 [source,groovy]
@@ -56,7 +58,7 @@ class ControllerTraitInjector implements TraitInjector {
 
 The above `TraitInjector` will add the `SomeTrait` to all controllers. The `getArtefactTypes` method defines the types of artefacts that the trait should be applied to.
 
-==== Applying traits conditionally
+== Applying traits conditionally
 A `TraitInjector` implementation can also implement the link:{api}grails/compiler/ast/SupportsClassNode.html[SupportsClassNode] interface to apply traits to only those artefacts which satisfy a custom requirement.
 For example, if a trait should only be applied if the target artefact class has a specific annotation, it can be done as below
 

grails-doc/src/en/guide/plugins/hookingIntoRuntimeConfiguration.adoc

@@ -17,10 +17,12 @@ specific language governing permissions and limitations
 under the License.
 ////
 
+= Hooking into Runtime Configuration
+
 Grails provides a number of hooks to leverage the different parts of the system and perform runtime configuration by convention.
 
 
-==== Hooking into the Grails Spring configuration
+== Hooking into the Grails Spring configuration
 
 
 First, you can hook in Grails runtime configuration overriding the `doWithSpring` method from the link:{api}grails/plugins/Plugin.html[Plugin] class and returning a closure that defines additional beans. For example the following snippet is from one of the core Grails plugins that provides link:i18n.html[i18n] support:
@@ -51,15 +53,15 @@ class I18nGrailsPlugin extends Plugin {
 This plugin configures the Grails `messageSource` bean and a couple of other beans to manage Locale resolution and switching. It using the link:spring.html#theBeanBuilderDSLExplained[Spring Bean Builder] syntax to do so.
 
 
-==== Customizing the Servlet Environment
+== Customizing the Servlet Environment
 
 
 In previous versions of Grails it was possible to dynamically modify the generated `web.xml`. From Grails 3.x+ there is no `web.xml` file and it is not possible to programmatically modify the `web.xml` file anymore.
 
 However, it is possible to perform the most commons tasks of modifying the Servlet environment in Grails 3.x and above.
 
 
-==== Adding New Servlets
+== Adding New Servlets
 
 
 If you want to add a new Servlet instance the simplest way is simply to define a new Spring bean in the `doWithSpring` method:
@@ -83,7 +85,7 @@ Closure doWithSpring() {{->
 ----
 
 
-==== Adding New Servlet Filters
+== Adding New Servlet Filters
 
 
 Just like Servlets, the simplest way to configure a new filter is to simply define a Spring bean:
@@ -109,7 +111,7 @@ myFilter(FilterRegistrationBean) {
 NOTE: Grails' internal registered filters (`GrailsWebRequestFilter`, `HiddenHttpMethodFilter` etc.) are defined by incrementing `HIGHEST_PRECEDENCE` by 10 thus allowing several filters to be inserted before or between Grails' filters.
 
 
-==== Doing Post Initialisation Configuration
+== Doing Post Initialisation Configuration
 
 
 Sometimes it is useful to be able do some runtime configuration after the Spring {springapi}org/springframework/context/ApplicationContext.html[ApplicationContext] has been built. In this case you can define a `doWithApplicationContext` closure property.

grails-doc/src/en/guide/plugins/participatingInAutoReloadEvents.adoc

@@ -17,8 +17,10 @@ specific language governing permissions and limitations
 under the License.
 ////
 
+= Participating in Auto Reload Events
 
-==== Monitoring Resources for Changes
+
+== Monitoring Resources for Changes
 
 
 Often it is valuable to monitor resources for changes and perform some action when they occur. This is how Grails implements advanced reloading of application state at runtime. For example, consider this simplified snippet from the Grails `ServicesPlugin`:
@@ -57,7 +59,7 @@ The `event` object defines a number of useful properties:
 These objects are available to help you apply the appropriate changes based on what changed. In the "Services" example above, a new service bean is re-registered with the `ApplicationContext` when one of the service classes changes.
 
 
-==== Influencing Other Plugins
+== Influencing Other Plugins
 
 
 In addition to reacting to changes, sometimes a plugin needs to "influence" another.
@@ -72,7 +74,7 @@ def influences = ['controllers']
 ----
 
 
-==== Observing other plugins
+== Observing other plugins
 
 
 If there is a particular plugin that you would like to observe for changes but not necessary watch the resources that it monitors you can use the "observe" property:

grails-doc/src/en/guide/plugins/providingBasicArtefacts.adoc

@@ -17,8 +17,10 @@ specific language governing permissions and limitations
 under the License.
 ////
 
+= Providing Basic Artefacts
 
-==== Add Command Line Commands
+
+== Add Command Line Commands
 
 
 A plugin can add new commands to the Grails interactive shell in one of two ways. First, using the link:{commandLineRef}create-script.html[create-script] you can create a code generation script which will become available to the application. The `create-script` command will create the script in the `src/main/scripts` directory:
@@ -93,7 +95,7 @@ The main difference between code generation scripts and `ApplicationCommand` ins
 In Grails 2.x Gant scripts could be used to perform both these tasks, from Grails 3.x+ code generation and interacting with runtime application state has been cleanly separated.
 
 
-==== Adding a new grails-app artifact (Controller, Tag Library, Service, etc.)
+== Adding a new grails-app artifact (Controller, Tag Library, Service, etc.)
 
 
 A plugin can add new artifacts by creating the relevant file within the `grails-app` tree.
@@ -107,7 +109,7 @@ A plugin can add new artifacts by creating the relevant file within the `grails-
 ----
 
 
-==== Providing Views, Templates and View resolution
+== Providing Views, Templates and View resolution
 
 
 When a plugin provides a controller it may also provide default views to be rendered. This is an excellent way to modularize your application through plugins. Grails' view resolution mechanism will first look for the view in the application it is installed into and if that fails will attempt to look for the view within the plugin. This means that you can override views provided by a plugin by creating corresponding GSPs in the application's `grails-app/views` directory.
@@ -124,7 +126,7 @@ However if the view uses templates that are also provided by the plugin then the
 Note the usage of the `plugin` attribute, which contains the name of the plugin where the template resides. If this is not specified then Grails will look for the template relative to the application.
 
 
-==== Excluded Artefacts
+== Excluded Artefacts
 
 By default Grails excludes the following files during the packaging process:
 

grails-doc/src/en/guide/plugins/repositories.adoc

@@ -17,8 +17,10 @@ specific language governing permissions and limitations
 under the License.
 ////
 
+= Plugin Repositories
 
-==== Distributing Plugins in the Grails Central Plugin Repository
+
+== Distributing Plugins in the Grails Central Plugin Repository
 
 
 The preferred way to distribute plugin is to publish to the official Grails Central Plugin Repository. This will make your plugin visible to the link:{commandLineRef}list-plugins.html[list-plugins] command: