Merge pull request #26670 from ebullient/docs-readme

Docs: Move docs/README.adoc to docs reference
quarkusio · Aug 2, 2022 · c6ed339 · c6ed339
2 parents f2e4c80 + edfda89
commit c6ed339
Show file tree

Hide file tree

Showing 4 changed files with 54 additions and 50 deletions.
diff --git a/docs/src/main/asciidoc/README.adoc b/docs/src/main/asciidoc/README.adoc
@@ -1,49 +1,12 @@
-= How to Create Quarkus Documentation
-include::./attributes.adoc[]
+= README: Quarkus documentation
+include::attributes.adoc[]
 
-This guide describes the asciidoc format and conventions that Quarkus has adopted.
+Quarkus documentation uses asciidoc syntax.
 
-== References
+A gradual refactoring effort is underway to reshape Quarkus documentation to make it easier to both read and write (see xref:doc-concepts.adoc[Quarkus documentation concepts] for more on this transition).
 
-The following links provide background on the general conventions and Asciidoc syntax.
+For more information on contributing to Quarkus docs, see:
 
-* https://redhat-documentation.github.io/asciidoc-markup-conventions/[AsciiDoc Mark-up Quick Reference for Documentation]
-* https://docs.asciidoctor.org/[Asciidoctor Documentation Site]
-* https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference]
-
-== Variables for Use in Documents
-
-The following variables externalize key information that can change over time, and so references
-to such information should be done by using the variable inside of {} curly brackets. The
-complete list of externalized variables for use is given in the following table:
-
-.Variables
-[cols="<m,<m,<2",options="header"]
-|===
-|Property Name|Value|Description
-|\{quarkus-version}|{quarkus-version}|The current version of the project.
-|\{quarkus-home-url}|{quarkus-home-url}| The location of the project home page.
-|\{quarkus-site-getting-started}|{quarkus-site-getting-started}| The location of the getting started page.
-
-|\{quarkus-org-url}|{quarkus-org-url}| The location of the project GitHub organization.
-|\{quarkus-base-url}|{quarkus-base-url}| Quarkus GitHub URL common base prefix.
-|\{quarkus-clone-url}|{quarkus-clone-url}| Quarkus URL for git clone referenced by the documentation.
-|\{quarkus-archive-url}|{quarkus-archive-url}| Quarkus URL to main source archive.
-|\{quarkus-blob-url}|{quarkus-blob-url}| Quarkus URL to main blob source tree; used for referencing source files.
-|\{quarkus-tree-url}|{quarkus-tree-url}| Quarkus URL to main source tree root; used for referencing directories.
-|\{quarkus-issues-url}|{quarkus-issues-url}| Quarkus URL to the issues page.
-|\{quarkus-images-url}|{quarkus-images-url}| Quarkus URL to set of container images delivered for Quarkus.
-
-|\{quarkus-chat-url}|{quarkus-chat-url} | URL of our chat.
-|\{quarkus-mailing-list-subscription-email}|{quarkus-mailing-list-subscription-email} | Email used to subscribe to our mailing list.
-|\{quarkus-mailing-list-index}|{quarkus-mailing-list-index} | Mailing list index page.
-
-|\{quickstarts-base-url}|{quickstarts-base-url}| Quickstarts URL common base prefix.
-|\{quickstarts-clone-url}|{quickstarts-clone-url}| Quickstarts URL for git clone referenced by the documentation.
-|\{quickstarts-archive-url}|{quickstarts-archive-url}| Quickstarts URL to main source archive.
-|\{quickstarts-blob-url}|{quickstarts-blob-url}| Quickstarts URL to main blob source tree; used for referencing source files.
-|\{quickstarts-tree-url}|{quickstarts-tree-url}| Quickstarts URL to main source tree root; used for referencing directories.
-
-|\{graalvm-version}|{graalvm-version}| Recommended GraalVM version to use.
-|\{graalvm-flavor}|{graalvm-flavor}| The full flavor of GraalVM to use e.g. `19.3.1-java11`. Make sure to use a `java11` version.
-|===
+- xref:doc-contribute-docs-howto.adoc[How to contribute documentation]
+- xref:doc-concepts.adoc[Quarkus documentation concepts]
+- xref:doc-reference.adoc[Quarkus documentation reference]
diff --git a/...oc/doc-contribute-quarkus-docs-howto.adoc → ...n/asciidoc/doc-contribute-docs-howto.adoc b/...oc/doc-contribute-quarkus-docs-howto.adoc → ...n/asciidoc/doc-contribute-docs-howto.adoc
@@ -3,8 +3,8 @@ 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
 ////
-[id="howto-contribute-quarkus-docs"]
-= How to contribute to Quarkus documentation
+[id="howto-contribute-docs"]
+= How to contribute documentation
 include::attributes.adoc[]
 :toc: preamble
 :asciidoc: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/

diff --git a/docs/src/main/asciidoc/doc-reference.adoc b/docs/src/main/asciidoc/doc-reference.adoc
@@ -69,7 +69,13 @@ Suffix:: The file name should reflect the type of document:
 
 == Asciidoc syntax
 
-Quarkus docs are built from source written using https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[Asciidoc] syntax.
+Quarkus docs use Asciidoc syntax.
+The following links provide background on Asciidoc syntax and general conventions.
+
+* https://redhat-documentation.github.io/asciidoc-markup-conventions/[AsciiDoc Mark-up Quick Reference for Documentation]
+* https://docs.asciidoctor.org/asciidoc/latest/[Asciidoctor User Manual]
+* https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference]
+
 
 === Semantic line breaks
 
@@ -152,5 +158,39 @@ xref:{doc-guides}/doc-concepts.adoc[Quarkus Documentation concepts] <1>
 ----
 <1> The cross reference starts with `xref:`, uses a cross-reference source attribute(`\{doc-guides}`), and provides a readable description: `[Quarkus Documentation concepts]`
 
-
-
+=== Variables for use in documents
+
+The following variables externalize key information that can change over time, and so references
+to such information should be done by using the variable inside of {} curly brackets. The
+complete list of externalized variables for use is given in the following table:
+
+.Variables
+[cols="<m,<m,<2",options="header"]
+|===
+|Property Name|Value|Description
+|\{quarkus-version}|{quarkus-version}|The current version of the project.
+|\{quarkus-home-url}|{quarkus-home-url}| The location of the project home page.
+|\{quarkus-site-getting-started}|{quarkus-site-getting-started}| The location of the getting started page.
+
+|\{quarkus-org-url}|{quarkus-org-url}| The location of the project GitHub organization.
+|\{quarkus-base-url}|{quarkus-base-url}| Quarkus GitHub URL common base prefix.
+|\{quarkus-clone-url}|{quarkus-clone-url}| Quarkus URL for git clone referenced by the documentation.
+|\{quarkus-archive-url}|{quarkus-archive-url}| Quarkus URL to main source archive.
+|\{quarkus-blob-url}|{quarkus-blob-url}| Quarkus URL to main blob source tree; used for referencing source files.
+|\{quarkus-tree-url}|{quarkus-tree-url}| Quarkus URL to main source tree root; used for referencing directories.
+|\{quarkus-issues-url}|{quarkus-issues-url}| Quarkus URL to the issues page.
+|\{quarkus-images-url}|{quarkus-images-url}| Quarkus URL to set of container images delivered for Quarkus.
+
+|\{quarkus-chat-url}|{quarkus-chat-url} | URL of our chat.
+|\{quarkus-mailing-list-subscription-email}|{quarkus-mailing-list-subscription-email} | Email used to subscribe to our mailing list.
+|\{quarkus-mailing-list-index}|{quarkus-mailing-list-index} | Mailing list index page.
+
+|\{quickstarts-base-url}|{quickstarts-base-url}| Quickstarts URL common base prefix.
+|\{quickstarts-clone-url}|{quickstarts-clone-url}| Quickstarts URL for git clone referenced by the documentation.
+|\{quickstarts-archive-url}|{quickstarts-archive-url}| Quickstarts URL to main source archive.
+|\{quickstarts-blob-url}|{quickstarts-blob-url}| Quickstarts URL to main blob source tree; used for referencing source files.
+|\{quickstarts-tree-url}|{quickstarts-tree-url}| Quickstarts URL to main source tree root; used for referencing directories.
+
+|\{graalvm-version}|{graalvm-version}| Recommended GraalVM version to use.
+|\{graalvm-flavor}|{graalvm-flavor}| The full flavor of GraalVM to use e.g. `19.3.1-java11`. Make sure to use a `java11` version.
+|===
diff --git a/docs/src/main/java/io/quarkus/docs/generation/YamlMetadataGenerator.java b/docs/src/main/java/io/quarkus/docs/generation/YamlMetadataGenerator.java
@@ -63,6 +63,7 @@ public static void main(String[] args) throws Exception {
         try (Asciidoctor asciidoctor = Asciidoctor.Factory.create()) {
             try (Stream<Path> pathStream = Files.list(rootDir)) {
                 pathStream.filter(path -> !path.endsWith("attributes.adoc"))
+                        .filter(path -> !path.getFileName().toString().startsWith("README"))
                         .filter(path -> path.getFileName().toString().endsWith(".adoc"))
                         .forEach(path -> {
                             Document doc = asciidoctor.loadFile(path.toFile(), options);