Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Move docs/README.adoc to docs reference #26670

Merged
merged 1 commit into from
Aug 2, 2022
Merged

Docs: Move docs/README.adoc to docs reference #26670

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 8 additions & 45 deletions docs/src/main/asciidoc/README.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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]
4 changes: 2 additions & 2 deletions ...oc/doc-contribute-quarkus-docs-howto.adoc → ...n/asciidoc/doc-contribute-docs-howto.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/
Expand Down
46 changes: 43 additions & 3 deletions docs/src/main/asciidoc/doc-reference.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.
|===
1 change: 1 addition & 0 deletions docs/src/main/java/io/quarkus/docs/generation/YamlMetadataGenerator.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down