Merge pull request #33619 from ebullient/docs-errors

ebullient · web-flow · commit 496251a4dbab · 2023-06-15T17:13:40.000-04:00
Show metadata errors in the docs build
diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml
@@ -55,7 +55,15 @@ jobs:
 
       - name: Build Docs
         run: |
-          ./mvnw -e -B --settings .github/mvn-settings.xml clean package -pl docs -Dasciidoctor.fail-if=DEBUG
+          if ./mvnw -e -B --settings .github/mvn-settings.xml clean package -pl docs -Dasciidoctor.fail-if=DEBUG ; then
+            echo "Build ok"
+          else
+            if [ -f docs/target/metadataErrors.md ]; then
+              echo "### Document Metadata Errors" >> $GITHUB_STEP_SUMMARY
+              cat docs/target/metadataErrors.md >> $GITHUB_STEP_SUMMARY
+            fi
+            exit 1
+          fi
 
       - name: Store PR id
         run: echo ${{ github.event.number }} > pr-id.txt
diff --git a/docs/pom.xml b/docs/pom.xml
@@ -3003,7 +3003,7 @@
                     </execution>
                     <execution>
                         <id>generate-doc-manifests</id>
-                        <phase>prepare-package</phase>
+                        <phase>package</phase>
                         <goals>
                             <goal>java</goal>
                         </goals>
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
@@ -6,12 +6,13 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id="acme-serve-http-requests-tutorial"]
 = Serve Http requests using the Acme extension
 include::_attributes.adoc[]
+:diataxis-type: tutorial
 :categories: web
 :extension-status: experimental
 
-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).
-We will also use Quarkus dev mode for iterative development and test.
+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).
+We will also use Quarkus dev mode for iterative development and testing.
 
 include::{includes}/extension-status.adoc[]
 
diff --git a/docs/src/main/asciidoc/_templates/template-concept.adoc b/docs/src/main/asciidoc/_templates/template-concept.adoc
@@ -4,14 +4,15 @@ and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 ////
-TODO: xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines] for details
-- Title should have an implied "Understanding..." in front. 
-- ID should end with '-concept' (using the filename works)
-- choose appropriate categories
+TODO: 
+- Title: https://quarkus.io/guides/doc-reference#titles-headings
+- Use the file name as the ID
+- Choose appropriate categories: https://quarkus.io/guides/doc-reference#categories
 ////
-[id="...-concept"]
+[id="..."]
 = Title using sentence capitalization
 include::_attributes.adoc[]
+:diataxis-type: concept
 :categories: ...
 ////
 :extension-status: preview
diff --git a/docs/src/main/asciidoc/_templates/template-howto.adoc b/docs/src/main/asciidoc/_templates/template-howto.adoc
@@ -4,14 +4,15 @@ and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 ////
-TODO: See xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines] for details
-- Title should have an implied "How to..." in front.
-- ID should end with '-howto' (using the filename works)
-- choose appropriate categories
+TODO:
+- Title: https://quarkus.io/guides/doc-reference#titles-headings
+- Use the file name as the ID
+- Choose appropriate categories: https://quarkus.io/guides/doc-reference#categories
 ////
-[id="...-howto"]
+[id="..."]
 = Title using sentence capitalization
 include::_attributes.adoc[]
+:diataxis-type: howto
 :categories: ...
 ////
 :extension-status: preview
diff --git a/docs/src/main/asciidoc/_templates/template-reference.adoc b/docs/src/main/asciidoc/_templates/template-reference.adoc
@@ -4,14 +4,15 @@ and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 ////
-TODO: See xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines] for details
-- Title should have an implied "About..." in front. 
-- ID should end with '-reference' (using the filename works)
-- choose appropriate categories
+TODO: 
+- Title: https://quarkus.io/guides/doc-reference#titles-headings
+- Use the file name as the ID
+- Choose appropriate categories: https://quarkus.io/guides/doc-reference#categories
 ////
-[id="...-reference"]
+[id="..."]
 = Title using sentence capitalization
 include::_attributes.adoc[]
+:diataxis-type: reference
 :categories: ...
 ////
 :extension-status: preview
diff --git a/docs/src/main/asciidoc/_templates/template-tutorial.adoc b/docs/src/main/asciidoc/_templates/template-tutorial.adoc
@@ -4,14 +4,15 @@ and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 ////
-TODO: See xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines]for details
-- Finish a sentence like: "Create a ...", "How to ..." 
-- ID should end with '-tutorial' (using the filename works)
-- choose appropriate categories 
+TODO: 
+- Title: https://quarkus.io/guides/doc-reference#titles-headings
+- Use the file name as the ID
+- Choose appropriate categories: https://quarkus.io/guides/doc-reference#categories
 ////
-[id="...-tutorial"]
+[id="..."]
 = Title using sentence capitalization
 include::_attributes.adoc[]
+:diataxis-type: tutorial
 :categories: ...
 ////
 :extension-status: preview
diff --git a/docs/src/main/asciidoc/doc-concept.adoc b/docs/src/main/asciidoc/doc-concept.adoc
@@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id="doc-concept"]
 = Quarkus documentation content types
 include::_attributes.adoc[]
+:diataxis-type: concept
 :categories: contributing
 :fn-diataxis: footnote:diataxis[Procida, D. Diátaxis documentation framework. https://diataxis.fr/]
 
diff --git a/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc b/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc
@@ -5,6 +5,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id="doc-contribute-howto"]
 = Contribute to Quarkus documentation
 include::_attributes.adoc[]
+:diataxis-type: howto
 :categories: contributing
 :fn-diataxis: footnote:diataxis[Procida, D. Diátaxis documentation framework. https://diataxis.fr/]
 
@@ -39,28 +40,32 @@ To ensure that your content shows up correctly on the link:https://quarkus.io/gu
 TIP: To help you decide, see the content type descriptions in xref:{doc-guides}/doc-reference.adoc#titles-and-headings[Titles and headings] on the "About Quarkus documentation" page.
 
 . Go to the `src/main/asciidoc/_templates` directory, and make a copy of the relevant template for the content type you have chosen. Be sure to:
-** Use the filename syntax of`<category>-<titlekeyword>-<titlekeyword>-<content-type>.adoc`. For example, `security-basic-authentication-tutorial.adoc`.
+** Use the filename syntax of`<category>-<titlekeyword>-<titlekeyword>.adoc`. For example, `security-basic-authentication.adoc`.
+** Include the diataxis type (concept, howto, reference, tutorial) in the file name if it makes sense to do so.
+For example, `telemetry-micrometer.adoc` is a reference, and `telemetry-micrometer-tutorial.adoc` is a tutorial.
 ** Save the file to the `docs/src/main/asciidoc` folder in the `quarkus` repository.
 
 . Set the minimum required header information to ensure that the content renders correctly in the website portal and on the documentation home page, as outlined in the following example:
 +
 [source,asciidoc]
 ----
-[id="security-basic-authentication-howto"] <1>
+[id="security-basic-authentication"] <1>
 = Secure a Quarkus application with basic authentication <2>
 include::_attributes.adoc[] <3>
-:categories: security,web <4>
-<5>
+:diataxis-type: howto <4>
+:categories: security,web <5>
+<6>
 ----
-<1> Set the `id` value to be the same as the file name but without the extension. You can shorten this if the file name is too long.
+<1> Set the `id` value to be the same as the file name but without the extension. 
 <2> For information about how to create a good title for each content type, see xref:{doc-guides}/doc-reference.adoc#titles-and-headings[Titles and headings] on the "Quarkus style and content guidelines" page.
 <3> The `_attributes.adoc` include is required to ensure that attributes get resolved and the table of contents is generated.
-<4> Set at least one category to ensure that the content is findable on the link:https://quarkus.io/guides/[Quarkus documentation home page]. For a list of Quarkus categories, see xref:{doc-guides}/doc-reference.adoc#document-attributes-and-variables[Document attributes and variables] on the "Quarkus style and content guidelines" page.
-<5> Insert a blank line before the abstract.
+<4> Specify the diataxis type: `concept`, `howto`, `reference`, or `tutorial`.
+<5> Set at least one category to ensure that the content is findable on the link:https://quarkus.io/guides/[Quarkus documentation home page]. For a list of Quarkus categories, see xref:{doc-guides}/doc-reference.adoc#document-attributes-and-variables[Document attributes and variables] on the "Quarkus style and content guidelines" page.
+<6> Insert a blank line after all document attributes and before the abstract.
 +
 [IMPORTANT]
 ====
-Ensure there are no line breaks in the header section until after `:categories:` line.
+Ensure there are no blank lines between the document id and title, the attribute include (`include::_attributes.adoc[]`) and the declaration of other document attributes(`:attribute:`).
 ====
 
 . Add an abstract that describes the purpose of the guide.
diff --git a/docs/src/main/asciidoc/doc-create-tutorial.adoc b/docs/src/main/asciidoc/doc-create-tutorial.adoc
@@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id="doc-create-tutorial"]
 = Creating a tutorial
 include::_attributes.adoc[]
+:diataxis-type: tutorial
 :categories: contributing
 
 Create a new tutorial that guides users through creating, running, and testing a Quarkus application that uses annotations from an imaginary extension.
@@ -29,7 +30,8 @@ For this example, we will use `acme-serve-http-requests-tutorial.adoc`:
 
 - `acme-` will group this guide with other resources related to the acme extension
 - `serve-http-requests` is a derivative of the document title
-- `-tutorial.adoc` will indicate that this document is a tutorial
+- `-tutorial` will indicate that this document is a tutorial (optional)
+- `.adoc` to indicate this is an asciidoc file
 
 == Copy the tutorial template
 
@@ -46,7 +48,7 @@ include::_attributes.adoc[] // <3>
 :extension-status: experimental // <5>
 ----
 
-<1> Specify a unique id for the section in lower-kebab-case.
+<1> Use the file name as a unique id for the section.
 <2> Add the title as a top-level heading.
 <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.
diff --git a/docs/src/main/asciidoc/doc-reference.adoc b/docs/src/main/asciidoc/doc-reference.adoc
@@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id="doc-reference"]
 = Quarkus style and content guidelines
 include::_attributes.adoc[]
+:diataxis-type: reference
 :categories: contributing
 
 Guidelines are provided to help you to contribute clear and consistent content that is also sourced in the required diataxis structure and composition of Quarkus documentation.
@@ -132,13 +133,12 @@ Use all lowercase letters, separate words with hyphens, and avoid symbols and sp
 Prefix:: Use a common prefix to group-related documents.
 Documents related to writing and contributing to Quarkus docs share the `doc-` prefix, for example.
 
-Suffix:: The file name should reflect the document type:
-
-- Concept documents should end in `-concept.adoc`
-- How-to guides should end in `-howto.adoc`
-- References should end in `-reference.adoc`
-- Tutorials should end in `-tutorial.adoc`
+Suffix:: Use a suffix that reflects the document type (optional):
 
+- `-concept.adoc` for concept documents
+- `-howto.adoc` for how-to guides
+- `-reference.adoc` for references 
+- `-tutorial.adoc` for tutorials
 
 [[doc-structure]]
 == Document structure
@@ -156,13 +156,15 @@ Minimally, each document should define and id and a title, and include common at
 [id="doc-reference"] // <1>
 = Quarkus style and content guidelines // <2>
 \include::_attributes.adoc[] // <3>
-:categories: contributing // <4>
+:diataxis-type: {type} // <4>
+:categories: contributing // <5>
 ----
 
 <1> Use the filename as the ID for the document.
 <2> Define the document title following guidance in <<titles-headings>>.
 <3> Include common document attributes.
-<4> Specify the relevant <<categories>> (comma separated).
+<4> Specify the diataxis type: `concept`, `howto`, `reference`, or `tutorial`.
+<5> Specify the relevant <<categories>> (comma separated).
 
 [[doc-header-optional]]
 ==== Other common document header attributes
diff --git a/docs/src/main/asciidoc/security-architecture-concept.adoc b/docs/src/main/asciidoc/security-architecture-concept.adoc
@@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id="security-architecture-concept"]
 = Quarkus Security architecture
 include::_attributes.adoc[]
+:diataxis-type: concept
 :categories: security
 
 The Quarkus Security architecture provides several built-in authentication mechanisms and is highly customizable.
diff --git a/docs/src/main/asciidoc/security-authentication-mechanisms-concept.adoc b/docs/src/main/asciidoc/security-authentication-mechanisms-concept.adoc
@@ -1,6 +1,7 @@
 [id="security-authentication-mechanisms-concept"]
 = Authentication mechanisms in Quarkus
 include::_attributes.adoc[]
+:diataxis-type: concept
 :categories: security,web
 
 The Quarkus Security framework supports multiple authentication mechanisms, which you can use to secure your applications.
diff --git a/docs/src/main/asciidoc/security-authorize-web-endpoints-reference.adoc b/docs/src/main/asciidoc/security-authorize-web-endpoints-reference.adoc
@@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id="security-authorize-web-endpoints-reference"]
 = Authorization of web endpoints
 include::_attributes.adoc[]
+:diataxis-type: reference
 :categories: security,web
 
 Quarkus has an integrated pluggable web security layer. If security is enabled, all HTTP requests will have a permission check performed to make sure they are allowed to continue.
diff --git a/docs/src/main/asciidoc/security-basic-authentication-concept.adoc b/docs/src/main/asciidoc/security-basic-authentication-concept.adoc
@@ -1,6 +1,7 @@
 [id="security-basic-authentication-concept"]
 = Basic authentication
 include::_attributes.adoc[]
+:diataxis-type: concept
 :categories: security,web
 
 HTTP Basic authentication is one of the least resource-demanding techniques that enforce access controls to web resources. 
diff --git a/docs/src/main/asciidoc/security-basic-authentication-howto.adoc b/docs/src/main/asciidoc/security-basic-authentication-howto.adoc
@@ -1,6 +1,7 @@
 [id="security-basic-authentication-howto"]
 = Enable Basic authentication
 include::_attributes.adoc[]
+:diataxis-type: howto
 :categories: security
 
 Enable xref:security-basic-authentication-concept.adoc[Basic authentication] for your Quarkus project and allow users to authenticate with a username and password.
diff --git a/docs/src/main/asciidoc/security-basic-authentication-tutorial.adoc b/docs/src/main/asciidoc/security-basic-authentication-tutorial.adoc
@@ -1,6 +1,7 @@
 [id="security-basic-authentication-tutorial"]
 = Secure a Quarkus application with Basic authentication and Jakarta Persistence
 include::_attributes.adoc[]
+:diataxis-type: tutorial
 :categories: security,getting-started
 
 Secure your Quarkus application endpoints by combining the built-in Quarkus xref:security-basic-authentication-concept.adoc[Basic authentication] with the Jakarta Persistence identity provider to enable role-based access control (RBAC).
diff --git a/docs/src/main/asciidoc/security-identity-providers-concept.adoc b/docs/src/main/asciidoc/security-identity-providers-concept.adoc
@@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id="security-identity-providers-concept"]
 = Identity providers
 include::_attributes.adoc[]
+:diataxis-type: concept
 :categories: security
 
 In the Quarkus Security framework, identity providers play a key role in authentication and authorization, providing services for storing and verifying user identities.
diff --git a/docs/src/main/asciidoc/security-oidc-bearer-token-authentication-concept.adoc b/docs/src/main/asciidoc/security-oidc-bearer-token-authentication-concept.adoc
@@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id="security-oidc-bearer-token-authentication-concept"]
 = OpenID Connect (OIDC) Bearer authentication
 include::_attributes.adoc[]
+:diataxis-type: concept
 :categories: security,web
 
 Secure HTTP access to Jakarta REST (formerly known as JAX-RS) endpoints in your application with Bearer authentication by using the Quarkus OpenID Connect (OIDC) extension.
diff --git a/docs/src/main/asciidoc/security-oidc-bearer-token-authentication-tutorial.adoc b/docs/src/main/asciidoc/security-oidc-bearer-token-authentication-tutorial.adoc
@@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id="security-oidc-bearer-token-authentication-tutorial"]
 = Protect a service application by using OpenID Connect (OIDC) bearer authentication
 include::_attributes.adoc[]
+:diataxis-type: tutorial
 :categories: security
 
 Here, you use the Quarkus OpenID Connect (OIDC) extension to secure a Jakarta REST application using Bearer authentication.
diff --git a/docs/src/main/asciidoc/security-oidc-code-flow-authentication-concept.adoc b/docs/src/main/asciidoc/security-oidc-code-flow-authentication-concept.adoc
@@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id="security-oidc-code-flow-authentication-concept"]
 = OpenID Connect authorization code flow mechanism for protecting web applications
 include::_attributes.adoc[]
+:diataxis-type: concept
 :categories: security,web
 :toclevels: 4
 
diff --git a/docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc b/docs/src/main/asciidoc/security-oidc-code-flow-authentication-tutorial.adoc
@@ -1,6 +1,7 @@
 [id="security-oidc-code-flow-authentication-tutorial"]
 = Protect a web application by using OpenID Connect (OIDC) authorization code flow
 include::_attributes.adoc[]
+:diataxis-type: tutorial
 :categories: security,web
 
 With the Quarkus OpenID Connect (OIDC) extension, you can protect application HTTP endpoints by using the OIDC Authorization Code Flow mechanism.
diff --git a/docs/src/main/asciidoc/security-oidc-configuration-properties-reference.adoc b/docs/src/main/asciidoc/security-oidc-configuration-properties-reference.adoc
@@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id="security-oidc-configuration-properties-reference"]
 = OpenID Connect (OIDC) configuration properties
 include::_attributes.adoc[]
+:diataxis-type: reference
 :categories: security
 
 As a Quarkus developer, you configure the Quarkus OpenID Connect (OIDC) extension by setting the following properties in the `src/main/resources/application.properties` file.
diff --git a/docs/src/main/asciidoc/security-overview-concept.adoc b/docs/src/main/asciidoc/security-overview-concept.adoc
@@ -1,6 +1,7 @@
 [id="security-overview-concept"]
 = Quarkus Security overview
 include::_attributes.adoc[]
+:diataxis-type: concept
 :categories: security
 
 Quarkus Security is a framework that provides the architecture, multiple authentication and authorization mechanisms, and other tools for you to build secure and production-quality Java applications.
diff --git a/docs/src/main/asciidoc/security-proactive-authentication-concept.adoc b/docs/src/main/asciidoc/security-proactive-authentication-concept.adoc
@@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id="security-proactive-authentication-concept"]
 = Proactive authentication
 include::_attributes.adoc[]
+:diataxis-type: concept
 :categories: security,web
 
 Proactive authentication is enabled in Quarkus by default. This means that if an incoming request has a credential then that request will always be authenticated, even if the target page does not require authentication.
diff --git a/docs/src/main/asciidoc/security-vulnerability-detection-concept.adoc b/docs/src/main/asciidoc/security-vulnerability-detection-concept.adoc
@@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id="security-vulnerability-detection-concept"]
 = Security vulnerability detection and reporting in Quarkus
 include::_attributes.adoc[]
+:diataxis-type: concept
 :categories: security,contributing
 
 Most of the Quarkus tags are registered in the US link:https://nvd.nist.gov[National Vulnerability Database (NVD)] in Common Platform Enumeration (CPE) name format.
diff --git a/docs/src/main/asciidoc/telemetry-micrometer-tutorial.adoc b/docs/src/main/asciidoc/telemetry-micrometer-tutorial.adoc
@@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id="telemetry-micrometer-tutorial"]
 = Collect metrics using Micrometer
 :categories: observability
+:diataxis-type: tutorial
 include::_attributes.adoc[]
 
 Create an application that uses the Micrometer metrics library to collect runtime, extension and application metrics and expose them as a Prometheus (OpenMetrics) endpoint.
diff --git a/docs/src/main/asciidoc/telemetry-micrometer.adoc b/docs/src/main/asciidoc/telemetry-micrometer.adoc
@@ -6,6 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 [id=telemetry-micrometer]
 = Micrometer Metrics
 include::_attributes.adoc[]
+:diataxis-type: reference
 :categories: observability
 :summary: Use Micrometer to collect metrics produced by Quarkus, its extensions, and your application.
 :base-units: https://github.com/micrometer-metrics/micrometer/blob/main/micrometer-core/src/main/java/io/micrometer/core/instrument/binder/BaseUnits.java
diff --git a/docs/src/main/java/io/quarkus/docs/generation/YamlMetadataGenerator.java b/docs/src/main/java/io/quarkus/docs/generation/YamlMetadataGenerator.java
diff --git a/docs/src/test/java/io/quarkus/docs/ChangedFiles.java b/docs/src/test/java/io/quarkus/docs/ChangedFiles.java
diff --git a/docs/src/test/java/io/quarkus/docs/LintException.java b/docs/src/test/java/io/quarkus/docs/LintException.java
diff --git a/docs/src/test/java/io/quarkus/docs/YamlMetadataGeneratorTest.java b/docs/src/test/java/io/quarkus/docs/YamlMetadataGeneratorTest.java
diff --git a/docs/src/test/java/io/quarkus/docs/vale/LocalValeLintTest.java b/docs/src/test/java/io/quarkus/docs/vale/LocalValeLintTest.java
