Merge pull request #1251 from cescoffier/features/documentation-impro…

…vements

Mimic attribute inclusion

docs/src/main/asciidoc/0-glossary.adoc

@@ -1,17 +1,18 @@
+include::./attributes.adoc[]
 = Internal glossary
 
 This is not a document to be published outside.
 This is a collection of preferred term in the documentation and website.
-Please stay witin these terms for consistency.
+Please stay within these terms for consistency.
 
-Live reload:: for our `quarkus:dev` capability
-GraalVM:: preferred term for the VM creating native executable. No space.
-Substrate VM:: non-preferred. Only if you want to clarify which part of GraalVM we use.
-Native Executable:: the executable that is compiled to native 1s and 0s
-Docker image:: for the actual `Dockerfile` definition and when the tool chain is involved
-Container:: when we discuss Quarkus running in... containers
-Supersonic Subatomic Java:: our tagline
-Kubernetes Native Java:: our preferred tagline to say that we rock for containers 
-Developer Joy:: for everything going from live reload to the opinionated layer to a single config file
-Unify Imperative and Reactive:: imperative and reactive. 'Nuff said.
-Best of breed frameworks and standards:: when we explain our stack
+* Live reload:: for our `quarkus:dev` capability
+* GraalVM:: preferred term for the VM creating native executable. No space.
+* Substrate VM:: non-preferred. Only if you want to clarify which part of GraalVM we use.
+* Native Executable:: the executable that is compiled to native 1s and 0s
+* Docker image:: for the actual `Dockerfile` definition and when the tool chain is involved
+* Container:: when we discuss Quarkus running in... containers
+* Supersonic Subatomic Java:: our tagline
+* Kubernetes Native Java:: our preferred tagline to say that we rock for containers
+* Developer Joy:: for everything going from live reload to the opinionated layer to a single config file
+* Unify Imperative and Reactive:: imperative and reactive. 'Nuff said.
+* Best of breed frameworks and standards:: when we explain our stack

docs/src/main/asciidoc/README.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = How to Create {project-name} Documentation
 
 This guide describes the asciidoc format and conventions that the {project-name} has

docs/src/main/asciidoc/application-configuration-guide.adoc

@@ -1,3 +1,5 @@
+include::./attributes.adoc[]
+
 = {project-name} - Configuring Your Application
 
 Hardcoded values in your code is a _no go_ (even if we all did it at some point ;-)).

docs/src/main/asciidoc/application-lifecycle-events-guide.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Application Initialization and Termination
 
 You often need to execute custom actions when the application starts and clean up everything when the application stops.

docs/src/main/asciidoc/attributes.adoc

@@ -0,0 +1 @@
+

docs/src/main/asciidoc/building-native-image-guide.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Building a Native Image
 
 This guide covers:

docs/src/main/asciidoc/building-substrate-howto.adoc

@@ -1,8 +1,9 @@
-== {project-name} - Building a Custom SubstrateVM
+include::./attributes.adoc[]
+= {project-name} - Building a Custom SubstrateVM
 
-=== Prerequisites
+== Prerequisites
 
-==== Install JVMCI
+=== Install JVMCI
 
 Before anything can be done you must first install a JVMCI build.
 
@@ -24,7 +25,7 @@ export JAVA_HOME=/opt/labsjdk1.8.0_172-jvmci-0.46/
 export PATH=$JAVA_HOME/bin:$PATH
 ----
 
-==== Install MX
+=== Install MX
 
 Now you need to install Graal’s special build tool, `mx`.
 
@@ -34,7 +35,7 @@ git clone [email protected]:graalvm/mx.git
 export PATH=`pwd`/mx:$PATH
 ----
 
-=== Checkout and build SubstrateVM
+== Checkout and build SubstrateVM
 
 You can now check-out and build Substrate:
 
@@ -55,7 +56,7 @@ mx native-image HelloWorld
 ./helloworld
 ----
 
-=== Building a custom GraalVM distribution
+== Building a custom GraalVM distribution
 
 In order to create a custom GraalVM distribution (necessary for usage
 in quarkus) you must switch to the vm subdirectory, and use special

docs/src/main/asciidoc/cdi-reference.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Contexts and Dependency Injection
 
 :numbered:

docs/src/main/asciidoc/cli-tooling.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = Building {project-name} apps with {project-name} Command Line Interface (CLI)
 
 == Installing the CLI

docs/src/main/asciidoc/extension-authors-guide.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Extension Authors Guide
 
 :numbered:

docs/src/main/asciidoc/faq.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Frequently Asked Questions
 
 :toc: macro

docs/src/main/asciidoc/getting-started-guide.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Creating Your First Application
 
 :toc: macro

docs/src/main/asciidoc/getting-started-knative-guide.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 :experimental:
 
 = {project-name} - Deploying Knative Application to Kubernetes or OpenShift

docs/src/main/asciidoc/gradle-config.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Gradle Plugin Repositories
 
 // tag::repositories[]

docs/src/main/asciidoc/gradle-tooling.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = Building {project-name} apps with Gradle
 
 == Gradle configuration

docs/src/main/asciidoc/hibernate-orm-guide.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Using Hibernate ORM and JPA
 :config-file: application.properties
 

docs/src/main/asciidoc/index.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name}
 
 include::quarkus-intro.adoc[tag=intro]

docs/src/main/asciidoc/infinispan-client-guide.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Infinispan Client
 
 Infinispan is an in memory data grid that allows running in a server outside of application processes. This extension

docs/src/main/asciidoc/jwt-guide.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Using JWT RBAC
 :extension-name: Smallrye JWT
 :mp-jwt: MicroProfile JWT RBAC

docs/src/main/asciidoc/kotlin.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Using Kotlin
 
 https://kotlinlang.org/[Kotlin] is a very popular programming language that targets the JVM (amongst other environments). Kotlin has experienced a surge in popularity the last few years making it the most popular JVM language, except for Java of course.

docs/src/main/asciidoc/kubernetes-guide.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Deploying Application to Kubernetes and OpenShift
 
 This guide covers:

docs/src/main/asciidoc/logging-guide.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Configuring Logging
 
 This guide explains logging and how to configure it.

docs/src/main/asciidoc/maven-tooling.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = Building {project-name} apps with Maven
 
 [[build-tool-maven]]

docs/src/main/asciidoc/native-and-ssl-guide.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = Quarkus - Using SSL With Native Images
 
 We are quickly moving to an SSL-everywhere world so being able to use SSL is crucial.

docs/src/main/asciidoc/opentracing-guide.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Using OpenTracing
 
 This guide explains how your Quarkus application can utilize opentracing to provide distributed tracing for

docs/src/main/asciidoc/panache-jpa-guide.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Simplified Hibernate ORM and JPA with Panache
 :config-file: application.properties
 

docs/src/main/asciidoc/performance-measure.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Measuring Performance
 
 This guide covers:

docs/src/main/asciidoc/quarkus-intro.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = What is {project-name}
 
 :toc: macro

docs/src/main/asciidoc/rest-client-guide.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Using the REST Client
 
 This guide explains how to use the MicroProfile REST Client in order to interact with REST APIs

docs/src/main/asciidoc/rest-json-guide.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = Quarkus - Writing JSON REST Services
 
 JSON is now the _lingua franca_ between microservices.

docs/src/main/asciidoc/scheduled-guide.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Schedule Periodic Tasks
 
 Modern applications often need to run specific tasks periodically.

docs/src/main/asciidoc/security-guide.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Using Security
 
 Quarkus comes with integration with the Elytron security subsystem to allow for RBAC based on the

docs/src/main/asciidoc/spring-di-guide.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Using our Spring Dependency Injection compatibility layer
 
 While you are encouraged to use CDI annotations for injection, {project-name} provides a compatibility layer for Spring dependency injection in the form of the `spring-di` extension.

docs/src/main/asciidoc/tooling.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Using our Tooling
 
 {project-name} comes with a toolchain enabling developers from live reload all the way down to deploying a Kubernetes application.

docs/src/main/asciidoc/transaction-guide.adoc

@@ -1,11 +1,12 @@
+include::./attributes.adoc[]
 = Using Transactions in Quarkus
 
 Quarkus comes with a Transaction Manager and uses it to coordinate and expose transactions to your applications.
 Each extension dealing with persistence will integrate with it for you.
 And you will explicitly interact with transactions via CDI.
 This guide will walk you through all that.
 
-## Setting it up
+== Setting it up
 
 You don't need to worry about setting it up most of the time as extensions needing it will simply add it as a dependency.
 Hibernate ORM for example will include the transaction manager and set it up properly.
@@ -24,16 +25,16 @@ Add the following to your `pom.xml`:
 </dependencies>
 --
 
-## Starting and stopping transactions: defining your boundaries
+== Starting and stopping transactions: defining your boundaries
 
 You can define your transaction boundaries the easy way, or the less easy way :)
 
-### Declarative approach
+=== Declarative approach
 
 The easiest way to define your transaction boundaries is to use the `@Transactional` annotation on your entry method (`javax.transaction.Transactional`).
 
 [source,java]
---
+====
 @ApplicationScoped
 public class SantaClausService {
 
@@ -52,8 +53,7 @@ public class SantaClausService {
         }
     }
 }
---
-
+====
 <1> This annotation defines your transaction boundaries and will wrap this call within a transaction.
 <2> A `RuntimeException` crossing the transaction boundaries will rollback the transaction.
 
@@ -82,7 +82,7 @@ You can also programmatically ask for a transaction to be marked for rollback.
 Inject a `TransactionManager` for this.
 
 [source,java]
---
+====
 @ApplicationScoped
 public class SantaClausService {
 
@@ -102,17 +102,17 @@ public class SantaClausService {
         }
     }
 }
---
+====
 
 <1> Inject the `TransactionManager` to be able to activate `setRollbackOnly` semantic.
 <2> Programmatically decide to set the transaction for rollback.
 
-### API approach
+=== API approach
 
 The less easy way is to inject a `UserTransaction` and use the various transaction demarcation methods.
 
 [source,java]
---
+====
 @ApplicationScoped
 public class SantaClausService {
 
@@ -134,14 +134,14 @@ public class SantaClausService {
         }
     }
 }
---
+====
 
 [NOTE]
---
+====
 You cannot use `UserTransaction` in a method having a transaction started by a `@Transactional` call.
---
+====
 
-## Why always having a transaction manager?
+== Why always having a transaction manager?
 
 Does it work everywhere I want to?::
 

docs/src/main/asciidoc/validation-guide.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Validation with Hibernate Validator
 
 This guide covers how to use Hibernate Validator/Bean Validation for:

docs/src/main/asciidoc/websocket-guide.adoc

@@ -1,3 +1,4 @@
+include::./attributes.adoc[]
 = {project-name} - Using Web Sockets
 
 This guide explains how your Quarkus application can utilize web sockets to create interactive web applications.