Skip to content

Commit

Permalink
Get rid of {doc-guides} attribute in documentation
Browse files Browse the repository at this point in the history 
It has been mistakenly used in the newest guide that was added as shown in
#36474 where we had:
- one invalid link because of a missing /
- one invalid link because an incorrect attribute was used

We see it's risky and it has no more value since
we introduced the downstream archive as we automatically transform the
links there to point to either a local one or one that is upstream.

IIRC, Michelle already removed some and I don't think it's recommended
nowadays.

Note: I haven't handled the getting-started-devservices.adoc here on
purpose as Leonor is working on it. Will handle it if needed once
Leonor's PR is in.
  • Loading branch information
@gsmet
gsmet committed Oct 13, 2023
1 parent e337149 commit a6d4ede
Show file tree
Hide file tree
Showing 8 changed files with 33 additions and 36 deletions.
1 change: 0 additions & 1 deletion docs/src/main/asciidoc/_attributes-local.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,6 @@
:icons: font
:generated-dir: ../../../../target/asciidoc/generated
:code-examples: {generated-dir}/examples
:doc-guides: ./
:doc-examples: ./_examples
:imagesdir: ./images
:includes: ./_includes
Expand Down
1 change: 0 additions & 1 deletion docs/src/main/asciidoc/_templates/_attributes.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@
:idseparator: -
:icons: font
:code-examples: ../../../../../target/asciidoc/generated/examples
:doc-guides: ..
:doc-examples: ../_examples
:imagesdir: ../images
:includes: ../includes
12 changes: 6 additions & 6 deletions docs/src/main/asciidoc/_templates/template-concept.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
////
////
TODO:
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
Expand All @@ -16,7 +16,7 @@ include::_attributes.adoc[]
:categories: ...
////
:extension-status: preview
TODO: uncomment the above for experimental or tech-preview content.
TODO: uncomment the above for experimental or tech-preview content.
The document header ends at the first blank line. Do not remove the blank line between the header and the abstract summary.
////

Expand All @@ -30,16 +30,16 @@ include::{includes}/extension-status.adoc[]

== Create additional sections

Check warning on line 31 in docs/src/main/asciidoc/_templates/template-concept.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'Create additional sections'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Create additional sections'.", "location": {"path": "docs/src/main/asciidoc/_templates/template-concept.adoc", "range": {"start": {"line": 31, "column": 4}}}, "severity": "INFO"}

- xref:{doc-guides}/doc-concept.adoc#concept[Quarkus documentation content types: Concept guides]
- xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines]
- xref:../doc-concept.adoc#concept[Quarkus documentation content types: Concept guides]
- xref:../doc-reference.adoc[Quarkus style and content guidelines]

=== Create cross-references

Check warning on line 36 in docs/src/main/asciidoc/_templates/template-concept.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'Create cross-references'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Create cross-references'.", "location": {"path": "docs/src/main/asciidoc/_templates/template-concept.adoc", "range": {"start": {"line": 36, "column": 5}}}, "severity": "INFO"}

To create anchors for in-file and cross-file navigation, see the following detailed instructions in the Quarkus style and content guidelines.

* xref:{doc-guides}doc-contribute-docs-howto.adoc#anchors-howto[Cross-reference in-file and cross-file content by using anchors]
* xref:../doc-contribute-docs-howto.adoc#anchors-howto[Cross-reference in-file and cross-file content by using anchors]

* xref:{doc-guides}doc-reference.adoc#cross-references[Cross-references]
* xref:../doc-reference.adoc#cross-references[Cross-references]


== Guidelines for a good Concept doc

Check warning on line 45 in docs/src/main/asciidoc/_templates/template-concept.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'Guidelines for a good Concept doc'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Guidelines for a good Concept doc'.", "location": {"path": "docs/src/main/asciidoc/_templates/template-concept.adoc", "range": {"start": {"line": 45, "column": 4}}}, "severity": "INFO"}
Expand Down
10 changes: 5 additions & 5 deletions docs/src/main/asciidoc/_templates/template-howto.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,17 +45,17 @@ Your user will also be in the middle of something: define the starting-point tha

== Resources

- xref:{doc-guides}/doc-create-howto-tutorial.adoc[Tutorial: Create a How-To]
- xref:{doc-guides}/doc-concept.adoc#howto-guide[Quarkus documentation content types: How-to guides]
- xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines]
- xref:../doc-create-howto-tutorial.adoc[Tutorial: Create a How-To]
- xref:../doc-concept.adoc#howto-guide[Quarkus documentation content types: How-to guides]
- xref:../doc-reference.adoc[Quarkus style and content guidelines]

=== Create cross-references

Check warning on line 52 in docs/src/main/asciidoc/_templates/template-howto.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'Create cross-references'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Create cross-references'.", "location": {"path": "docs/src/main/asciidoc/_templates/template-howto.adoc", "range": {"start": {"line": 52, "column": 5}}}, "severity": "INFO"}

To create anchors for in-file and cross-file navigation, see the following detailed instructions in the Quarkus style and content guidelines.

* xref:{doc-guides}doc-contribute-docs-howto.adoc#anchors-howto[Cross-reference in-file and cross-file content by using anchors]
* xref:../doc-contribute-docs-howto.adoc#anchors-howto[Cross-reference in-file and cross-file content by using anchors]

* xref:{doc-guides}doc-reference.adoc#cross-references[Cross-references]
* xref:../doc-reference.adoc#cross-references[Cross-references]

== Guidelines for good How-To guides

Check warning on line 60 in docs/src/main/asciidoc/_templates/template-howto.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'Guidelines for good How-To guides'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Guidelines for good How-To guides'.", "location": {"path": "docs/src/main/asciidoc/_templates/template-howto.adoc", "range": {"start": {"line": 60, "column": 4}}}, "severity": "INFO"}

Expand Down
12 changes: 6 additions & 6 deletions docs/src/main/asciidoc/_templates/template-reference.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
////
////
TODO:
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
Expand All @@ -16,7 +16,7 @@ include::_attributes.adoc[]
:categories: ...
////
:extension-status: preview
TODO: uncomment the above for experimental or tech-preview content.
TODO: uncomment the above for experimental or tech-preview content.
The document header ends at the first blank line. Do not remove the blank line between the header and the abstract summary.
////

Expand All @@ -30,16 +30,16 @@ include::{includes}/extension-status.adoc[]

== Add additional sections

- xref:{doc-guides}/doc-concept.adoc#reference[Quarkus documentation content types: Reference guides]
- xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines]
- xref:../doc-concept.adoc#reference[Quarkus documentation content types: Reference guides]
- xref:../doc-reference.adoc[Quarkus style and content guidelines]

=== Create cross-references

Check warning on line 36 in docs/src/main/asciidoc/_templates/template-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'Create cross-references'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Create cross-references'.", "location": {"path": "docs/src/main/asciidoc/_templates/template-reference.adoc", "range": {"start": {"line": 36, "column": 5}}}, "severity": "INFO"}

To create anchors for in-file and cross-file navigation, see the following detailed instructions in the Quarkus style and content guidelines.

* xref:{doc-guides}doc-contribute-docs-howto.adoc#anchors-howto[Cross-reference in-file and cross-file content by using anchors]
* xref:../doc-contribute-docs-howto.adoc#anchors-howto[Cross-reference in-file and cross-file content by using anchors]

* xref:{doc-guides}doc-reference.adoc#cross-references[Cross-references]
* xref:../doc-reference.adoc#cross-references[Cross-references]

== Guidelines for a good reference

Check warning on line 44 in docs/src/main/asciidoc/_templates/template-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'Guidelines for a good reference'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Guidelines for a good reference'.", "location": {"path": "docs/src/main/asciidoc/_templates/template-reference.adoc", "range": {"start": {"line": 44, "column": 4}}}, "severity": "INFO"}

Expand Down
14 changes: 7 additions & 7 deletions docs/src/main/asciidoc/_templates/template-tutorial.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
////
////
TODO:
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
Expand All @@ -16,7 +16,7 @@ include::_attributes.adoc[]
:categories: ...
////
:extension-status: preview
TODO: uncomment the above for experimental or tech-preview content.
TODO: uncomment the above for experimental or tech-preview content.
The document header ends at the first blank line. Do not remove the blank line between the header and the abstract summary.
////

Expand All @@ -43,9 +43,9 @@ This file offers a few different variables that can be used to tweak what is sho
:sectnumlevels: 3
== Outline steps

- xref:{doc-guides}/doc-create-tutorial.adoc[Tutorial: Create a tutorial]
- xref:{doc-guides}/doc-concept.adoc#tutorial[Quarkus documentation content types: Tutorials]
- xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines]
- xref:../doc-create-tutorial.adoc[Tutorial: Create a tutorial]
- xref:../doc-concept.adoc#tutorial[Quarkus documentation content types: Tutorials]
- xref:../doc-reference.adoc[Quarkus style and content guidelines]

Each step should conclude with a comprehensible/observable result.

Expand All @@ -71,6 +71,6 @@ To help direct the reader to more information about the content topic, optionall

To create anchors for in-file and cross-file navigation, see the following detailed instructions in the Quarkus style and content guidelines.

* xref:{doc-guides}doc-contribute-docs-howto.adoc#anchors-howto[Cross-reference in-file and cross-file content by using anchors]
* xref:../doc-contribute-docs-howto.adoc#anchors-howto[Cross-reference in-file and cross-file content by using anchors]

* xref:{doc-guides}doc-reference.adoc#cross-references[Cross-references]
* xref:../doc-reference.adoc#cross-references[Cross-references]
12 changes: 6 additions & 6 deletions docs/src/main/asciidoc/doc-contribute-docs-howto.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@ Quarkus docs use link:https://asciidoc.org/[AsciiDoc] markup.
* You have an editor or IDE that provides syntax highlighting and previews for AsciiDoc, either natively or with a plugin.
* You have reviewed the following Quarkus contributor resources:
** The link:https://github.com/quarkusio/quarkus/blob/main/CONTRIBUTING.md#documentation[Documentation] section of the Quarkus "Contributing" guide.
** The xref:{doc-guides}/doc-reference.adoc[Quarkus style and content guidelines] for the required syntax, preferred style, and other conventions.
** The xref:{doc-guides}/doc-concept.adoc[Quarkus documentation content types].
** The xref:doc-reference.adoc[Quarkus style and content guidelines] for the required syntax, preferred style, and other conventions.
** The xref:doc-concept.adoc[Quarkus documentation content types].
* You have the https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc syntax reference] nearby.

== Locate the source files for Quarkus docs
Expand All @@ -38,7 +38,7 @@ To ensure that your content shows up correctly on the link:https://quarkus.io/gu

. Decide on a xref:doc-concept.adoc[Diataxis] content type that best fits the content that you are contributing.
+
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.
TIP: To help you decide, see the content type descriptions in xref: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>.adoc`. For example, `security-basic-authentication.adoc`.
Expand All @@ -58,10 +58,10 @@ include::_attributes.adoc[] <3>
<6>
----
<1> Set the `id` value to be the same as the file name but without the extension.

Check warning on line 60 in docs/src/main/asciidoc/doc-contribute-docs-howto.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/doc-contribute-docs-howto.adoc", "range": {"start": {"line": 60, "column": 39}}}, "severity": "INFO"}
<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.
<2> For information about how to create a good title for each content type, see xref: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> Specify the diataxis type: `concept`, `howto`, `reference`, or `tutorial`.

Check warning on line 63 in docs/src/main/asciidoc/doc-contribute-docs-howto.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'diataxis'?

Raw Output:
{"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'diataxis'?", "location": {"path": "docs/src/main/asciidoc/doc-contribute-docs-howto.adoc", "range": {"start": {"line": 63, "column": 17}}}, "severity": "WARNING"}
<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.
<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-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]
Expand All @@ -77,7 +77,7 @@ The first sentence of the abstract must explain the value and some benefit of th
There must also be a line break before and after the abstract.
====

For more information about the minimum header requirements, see xref:{doc-guides}/doc-reference.adoc#document-structure[Document structure] on the "Quarkus style and content guidelines" page.
For more information about the minimum header requirements, see xref:doc-reference.adoc#document-structure[Document structure] on the "Quarkus style and content guidelines" page.

[id="add-prerequisites"]
== Add a prerequisites section
Expand Down
7 changes: 3 additions & 4 deletions docs/src/main/asciidoc/doc-reference.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -227,7 +227,7 @@ If you end up with deeply nested sections, think about the following:
For example, if this is a reference, should some of this content be moved to a concept doc or how-to guide instead?
- Can the content be reorganized to make it simpler to consume?
See xref:{doc-guides}/doc-concept.adoc[Quarkus documentation content types] for more information about content types and organization.
See xref:doc-concept.adoc[Quarkus documentation content types] for more information about content types and organization.
====

== Links
Expand Down Expand Up @@ -264,7 +264,6 @@ We use attributes in our cross-references to ensure our docs can be built across
|Attribute|Description
|\{code-examples}|Relative path to directory containing collected example source files
|\{doc-examples}|Relative path to source examples for documentation guides
|\{doc-guides}|Relative path to documentation adoc files
|\{generated-dir}|Relative path to generated configuration `*.adoc` files
|\{imagesdir}|Relative path to directory containing images
|\{includes}|Relative path to directory containing partial/reusable content
Expand All @@ -275,9 +274,9 @@ When cross-referencing content, always use the inter-document `xref:` syntax and
.Cross-reference example
[source,asciidoc]
----
xref:{doc-guides}/doc-concept.adoc[Quarkus Documentation concepts] <1>
xref:doc-concept.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]`.
<1> The cross-reference starts with `xref:`, and provides a readable description: `[Quarkus Documentation concepts]`.

[[anchors-reference]]
=== Anchors for in-file and cross-file navigation

Check warning on line 282 in docs/src/main/asciidoc/doc-reference.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'Anchors for in-file and cross-file navigation'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Anchors for in-file and cross-file navigation'.", "location": {"path": "docs/src/main/asciidoc/doc-reference.adoc", "range": {"start": {"line": 282, "column": 5}}}, "severity": "INFO"}
Expand Down

0 comments on commit a6d4ede

Please sign in to comment.