Merge pull request quarkusio#29392 from ebullient/docs-header

Improve doc reference for specifying categories
gsmet · Nov 22, 2022 · 3baf6cc · 3baf6cc
2 parents d16119e + 4db7f00
commit 3baf6cc
Show file tree

Hide file tree

Showing 32 changed files with 189 additions and 122 deletions.
diff --git a/docs/src/main/asciidoc/_examples/acme-serve-http-requests-tutorial.adoctxt b/docs/src/main/asciidoc/_examples/acme-serve-http-requests-tutorial.adoctxt
@@ -5,8 +5,9 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 [id="tutorial-acme-serve-http-requests"]
 = Serve Http requests using the Acme extension
+include::_attributes.adoc[]
+:categories: web
 :extension-status: experimental
-include::attributes.adoc[]
 
 In this tutorial, we will create an application that uses unique annotations from the experimental acme extension to define two endpoints:
 a simple Http endpoint and an endpoint that emits Server-Sent Events (SSE).

diff --git a/docs/src/main/asciidoc/_templates/template-concepts.adoc b/docs/src/main/asciidoc/_templates/template-concepts.adoc
@@ -3,13 +3,21 @@ This document is maintained in the main Quarkus repository
 and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
+////
+TODO: See Quarkus documentation reference for details
+- Title should have an implied "Understanding..." in front. 
+- ID should start with 'concept-'
+- choose appropriate categories
+////
 [id="concept-..."]
 = Title using sentence capitalization
+include::_attributes.adoc[]
+:categories: ...
 ////
-TODO: If this is a concept related to an experimental or tech-preview extension, uncomment the following and set the appropriate status (otherwise delete)
 :extension-status: preview
+TODO: uncomment the above for for an experimental or tech-preview content. 
+The document header ends at the first blank line.
 ////
-include::_attributes.adoc[]
 
 A short introduction that summarizes or frames the concept.
 This summary should help a reader determine whether or not this document is what they want to read.

diff --git a/docs/src/main/asciidoc/_templates/template-howto.adoc b/docs/src/main/asciidoc/_templates/template-howto.adoc
@@ -4,15 +4,20 @@ and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 ////
-TODO: Title should have an implied "How to.." in front. See
+TODO: See Quarkus documentation reference for details
+- Title should have an implied "How to..." in front. 
+- ID should start with 'howto-'
+- choose appropriate categories
 ////
 [id="howto-..."]
 = Title using sentence capitalization
+include::_attributes.adoc[]
+:categories: ...
 ////
-TODO: If this is a reference for an experimental or tech-preview extension, uncomment the following and set the appropriate status (otherwise delete)
 :extension-status: preview
+TODO: uncomment the above for for an experimental or tech-preview content. 
+The document header ends at the first blank line.
 ////
-include::_attributes.adoc[]
 
 How-to guides are goal-oriented, and should help the reader accomplish a task (where there may be forks in the path).
 

diff --git a/docs/src/main/asciidoc/_templates/template-reference.adoc b/docs/src/main/asciidoc/_templates/template-reference.adoc
@@ -3,13 +3,21 @@ This document is maintained in the main Quarkus repository
 and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
+////
+TODO: See Quarkus documentation reference for details
+- Title should have an implied "About..." in front. 
+- ID should start with 'reference-'
+- choose appropriate categories
+////
 [id="reference-..."]
 = Title using sentence capitalization
+include::_attributes.adoc[]
+:categories: ...
 ////
-TODO: If this is a reference for an experimental or tech-preview extension, uncomment the following and set the appropriate status (otherwise delete)
 :extension-status: preview
+TODO: uncomment the above for for an experimental or tech-preview content. 
+The document header ends at the first blank line.
 ////
-include::_attributes.adoc[]
 
 A short introduction that describes the content of this reference.
 This summary should help a reader determine if this document is likely to contain the information they are looking for.

diff --git a/docs/src/main/asciidoc/_templates/template-tutorial.adoc b/docs/src/main/asciidoc/_templates/template-tutorial.adoc
@@ -3,13 +3,21 @@ This document is maintained in the main Quarkus repository
 and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
+////
+TODO: See Quarkus documentation reference for details
+- Finish a sentence like: "Create a ...", "How to ..." 
+- ID should start with 'tutorial-'
+- choose appropriate categories 
+////
 [id="tutorial-..."]
 = Title using sentence capitalization
+include::_attributes.adoc[]
+:categories: ...
 ////
-TODO: If this is a tutorial for an experimental or tech-preview extension, uncomment the following and set the appropriate status (otherwise delete)
 :extension-status: preview
+TODO: uncomment the above for for an experimental or tech-preview content. 
+The document header ends at the first blank line.
 ////
-include::_attributes.adoc[]
 
 Describe what the learner will accomplish (examples: build, create, construct, deploy; not: “you will learn...”).
 This short summary should help a reader determine if they want to engage with the content.

diff --git a/docs/src/main/asciidoc/cdi-integration.adoc b/docs/src/main/asciidoc/cdi-integration.adoc
@@ -8,7 +8,6 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 :summary: Learn how to integrate your extension with Quarkus' CDI container.
 include::_attributes.adoc[]
 :numbered:
-:toc:
 :toclevels: 2
 
 ArC, the CDI container, is bootstrapped at build time.

diff --git a/docs/src/main/asciidoc/cdi-reference.adoc b/docs/src/main/asciidoc/cdi-reference.adoc
@@ -10,7 +10,6 @@ include::_attributes.adoc[]
 :numbered:
 :sectnums:
 :sectnumlevels: 4
-:toc:
 
 Quarkus DI solution (also called ArC) is based on the https://jakarta.ee/specifications/cdi/2.0/cdi-spec-2.0.html[Contexts and Dependency Injection for Java 2.0, window="_blank"] specification.
 However, it is not a full CDI implementation verified by the TCK.

diff --git a/docs/src/main/asciidoc/cdi.adoc b/docs/src/main/asciidoc/cdi.adoc
@@ -10,7 +10,6 @@ include::_attributes.adoc[]
 :numbered:
 :sectnums:
 :sectnumlevels: 4
-:toc:
 
 In this guide we're going to describe the basic principles of the Quarkus programming model that is based on the https://jakarta.ee/specifications/cdi/2.0/cdi-spec-2.0.html[Contexts and Dependency Injection for Java 2.0, window="_blank"] specification.
 

diff --git a/docs/src/main/asciidoc/config-extending-support.adoc b/docs/src/main/asciidoc/config-extending-support.adoc
@@ -10,7 +10,6 @@ include::_attributes.adoc[]
 :numbered:
 :sectnums:
 :sectnumlevels: 4
-:toc:
 
 [[custom-config-source]]
 == Custom `ConfigSource`

diff --git a/docs/src/main/asciidoc/config-mappings.adoc b/docs/src/main/asciidoc/config-mappings.adoc
@@ -10,7 +10,6 @@ include::_attributes.adoc[]
 :numbered:
 :sectnums:
 :sectnumlevels: 4
-:toc:
 
 With config mappings it is possible to group multiple configuration properties in a single interface that
 share the same prefix.

diff --git a/docs/src/main/asciidoc/config-reference.adoc b/docs/src/main/asciidoc/config-reference.adoc
@@ -10,7 +10,6 @@ include::_attributes.adoc[]
 :numbered:
 :sectnums:
 :sectnumlevels: 4
-:toc:
 
 IMPORTANT: The content of this guide has been revised and split into additional topics. Please check the <<additional-information,Additional Information>> section.
 

diff --git a/docs/src/main/asciidoc/config-yaml.adoc b/docs/src/main/asciidoc/config-yaml.adoc
@@ -7,7 +7,6 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 include::_attributes.adoc[]
 :categories: core
 :summary: YAML as a Configuration Source.
-:toc:
 
 https://en.wikipedia.org/wiki/YAML[YAML] is a very popular format. Kubernetes relies heavily on the YAML format to
 write the various resource descriptors.

diff --git a/docs/src/main/asciidoc/config.adoc b/docs/src/main/asciidoc/config.adoc
@@ -11,7 +11,6 @@ include::_attributes.adoc[]
 IMPORTANT: The content of this guide and been revised and split into additional topics. Please check the
 <<additional-information,Additional Information>> section.
 
-:toc:
 
 Hardcoded values in your code are a _no-go_ (even if we all did it at some point ;-)).
 In this guide, we will learn how to configure a Quarkus application.

diff --git a/docs/src/main/asciidoc/continuous-testing.adoc b/docs/src/main/asciidoc/continuous-testing.adoc
@@ -7,12 +7,6 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 include::_attributes.adoc[]
 :categories: core
 :summary: Get early test feedback with Continuous Testing.
-:toc: macro
-:toclevels: 4
-:doctype: book
-:icons: font
-:docinfo1:
-
 :numbered:
 :sectnums:
 :sectnumlevels: 4

diff --git a/docs/src/main/asciidoc/doc-concepts.adoc b/docs/src/main/asciidoc/doc-concepts.adoc
@@ -27,7 +27,7 @@ Good concept guides:
 Their goal is to help the reader understand the concept.
 - do not teach, instruct or include reference information.
 If you need to refer to a tutorial, how-to, or reference guide, point the reader to where they can find it, but do not replicate that information directly in your concept guide.
-- provide background information and context to explain _why_ things work the way they do, or why they are built in a particular way.
+- provide background information and context to explain _why_ things work the way they do, or why they are built the way they are.
 You can cite design decisions, historical reasons, and technical constraints to reaffirm your points.
 - include specific examples to illustrate the explanation, but avoid making the explanation itself overly dependent on a specific technology or pattern of implementation.
 - analyze the concept from multiple perspectives and draw comparisons with alternative concepts discuss if it is relevant and useful for the reader's understanding.
@@ -79,7 +79,7 @@ Good tutorials:
 - include only enough information to complete the task. 
   They delegate to other documentation types (concepts or reference) to provide additional context.
 - focus on one way of doing the task. Alternative approaches are explored in other document types
-  (e.g. a how-to guide).
+  (a how-to guide, for example).
 
 
 
diff --git a/docs/src/main/asciidoc/doc-create-tutorial.adoc b/docs/src/main/asciidoc/doc-create-tutorial.adoc
@@ -13,7 +13,7 @@ Create a new tutorial that guides users through creating, running, and testing a
 == Prerequisites
 
 - Roughly 15 minutes
-- An editor or IDE that provides syntax highlighting and previews for asciidoc, either natively or using a plugin.
+- An editor or IDE that provides syntax highlighting and previews for AsciiDoc, either natively or using a plugin.
 - You should be familiar with the overview of what a xref:doc-concepts.adoc#tutorial[Tutorial] is.
 - Have the xref:doc-reference.adoc[Quarkus documentation reference] handy as a reference for required syntax and other conventions.
 
@@ -41,14 +41,16 @@ Copy `docs/src/main/diataxis/_templates/template-tutorial.adoc` from the Quarkus
 ----
 [id="tutorial-acme-serve-http-requests"] // <1>
 = Serve Http requests using the Acme extension // <2>
-:extension-status: experimental // <3>
-include::_attributes.adoc[] // <4>
+include::_attributes.adoc[] // <3>
+:categories: web // <4>
+:extension-status: experimental // <5>
 ----
 
 <1> Specify a unique id for the section in lower-kebab-case.
 <2> Add the title as a top-level heading.
-<3> Our imaginary `acme` extension is experimental, so we include the extension status declaration in the header.
-<4> Include additional attributes that help define consistent formatting and provide source portability.
+<3> Include additional attributes that help define consistent formatting and provide source portability.
+<4> Specify the `web` category, as our imaginary extension works with Http requests.
+<5> Our imaginary `acme` extension is experimental, so we include the extension status declaration in the header.
 
 .Document Preview
 --
@@ -85,7 +87,7 @@ It uses the extension status attribute defined in the header.
 
 .Document Preview
 --
-The preview of your document should now include an admonition box below the abstract explaining that the plugin is experimental technology, and describing what can be expected in terms of stability and/or support for experimental technologies.
+The preview of your document should now include an admonition box below the abstract explaining that the plugin is experimental technology, and describing what can be expected in terms of stability or support for experimental technologies.
 --
 
 == Define Prerequisites
@@ -109,7 +111,7 @@ The `curl` command line utility is also used to manually test the endpoint.
 
 <1> Declare that our hypothetical tutorial will take about 30 minutes to complete.
 <2> Declare that our nonsensical acme extension also requires a container runtime.
-<3> For simplicity in this tutorial, we will avoid graalvm/mandrel prerequisites
+<3> For simplicity in this tutorial, we will avoid GraalVM and Mandrel prerequisites.
 <4> Include the common file that provides text describing prerequisites.
 
 .Document Preview
@@ -146,7 +148,7 @@ include::{includes}/devtools/create-app.adoc[] // <6>
 <1> Enable section numbering
 <2> Create a second level heading for the first step
 <3> Describe the step briefly
-<4> Define the maven/gradle artifact id
+<4> Define the artifact id (Maven or Gradle)
 <5> List the extensions required by this project
 <6> Use common text to describe how to create a project
 
@@ -205,9 +207,9 @@ public class MyAcmeApplication {
 
 There are a few things to notice in this code sample:
 
-- There are callouts as comments on some lines, and their numbering is not sequential.
+- AsciiDoc callouts are shown as comments on some lines, and their numbering is not sequential.
 
-- There are Asciidoc content regions defined by tag pairs (`tag::` and `end::`) in comments surrounding different sections of code.
+- AsciiDoc content regions are defined by tag pairs (`tag::` and `end::`) in comments surrounding different sections of code.
 
 === Provide concise subsequent steps
 
@@ -243,7 +245,7 @@ Some things to notice about these instructions:
 - We describe what `@Anvil` is providing in the specific case covered by this tutorial.
 
 WARNING: Be careful with the amount of explanation given in a tutorial.
-Include enough information in the tutorial to help the user determine what other resource (howto, concept, or reference) they should look at next.
+Include enough information in the tutorial to help the user determine what other resource (`howto`, `concept`, or `reference`) they should look at next.
 
 .Document Preview
 --
@@ -360,7 +362,7 @@ You should see a message that 2 tests were run, and both were successful.
 
 A few things to note:
 
-- We're using the asciidoc region tag to include only one region of the target file.
+- We're using the AsciiDoc region tag to include only one region of the target file.
 
 - We do not go into detail explaining concepts:
 
@@ -399,7 +401,7 @@ Your preview should now contain an unnumbered `Summary` section.
 Congratulations!
 You have created a tutorial that describes how to create an application that uses annotations of dubious merit from a hypothetical extension.
 
-If you wish, you may compare your result against the complete worked example:
+Compare your result against the complete worked example:
 
 [source,asciidoc]
 -----