From d3c5520d87f1be5ed034281cf9e71ed6e56a6150 Mon Sep 17 00:00:00 2001 From: Michelle Purcell Date: Thu, 22 Dec 2022 17:23:15 +0000 Subject: [PATCH] WIP: Docs- Add landing page & URL redirect info Fix typo Enhance content enhancements enhancements Further enhancements enhancements --- .../asciidoc/doc-contribute-docs-howto.adoc | 94 +++++++++++++++++-- 1 file changed, 84 insertions(+), 10 deletions(-) diff --git a/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc b/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc index 3e057e24e7a06b..2135ded9abb14a 100644 --- a/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc +++ b/docs/src/main/asciidoc/doc-contribute-docs-howto.adoc @@ -4,34 +4,96 @@ and pull requests should be submitted there: https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc //// [id="doc-contribute-howto"] -= How to contribute documentation += Contribute to Quarkus documentation include::_attributes.adoc[] :categories: contributing :fn-diataxis: footnote:diataxis[Procida, D. Diátaxis documentation framework. https://diataxis.fr/] -Outline the recommended steps for making successful contributions to Quarkus documentation. +Outlines the recommended steps for successfully contributing to the Quarkus documentation. == Prerequisites -Quarkus docs use AsciiDoc, a lightweight markup language. +Quarkus docs are sourced in AsciiDoc, a lightweight markup language. We suggest you have the following materials nearby: - An editor or IDE that provides syntax highlighting and previews for AsciiDoc, either natively or with a plugin. - The https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc syntax reference] -- The xref:{doc-guides}/doc-reference.adoc[Quarkus documentation reference] for required syntax and other conventions. +- The xref:{doc-guides}/doc-reference.adoc[Quarkus documentation reference] for the required syntax, preferred style, and other conventions. -== Sources +== Locate the source files for Quarkus docs - AsciiDoc files are in the `src/main/asciidoc` directory within the `docs` module of the {quarkus-base-url}/tree/main/docs[Quarkus GitHub repository]. - Configuration documentation is generated from JavaDoc comments in Java source files. - Java, YAML, and other source files can also be xref:doc-reference.adoc#reference-source-code[referenced] by AsciiDoc files. +- The link:https://quarkus.io/guides/[Quarkus documentation] menu page, also known as the doc index page, is sourced in the link:https://github.com/quarkusio/quarkusio.github.io[quarkusio.github.io] repository. + + +== Create Quarkus content in AsciiDoc + +To ensure that your content shows up correctly on the link:https://quarkus.io/guides/[Quarkus documentation home page], use the following steps: + +. Decide on a content type that best fits the content that you are contributing. ++ +TIP: To help you decide, use the *Content types* section in xref:{doc-guides}/doc-reference.adoc[Quarkus documentation reference]. ++ +. 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`---.adoc`. For example, `security-basic-authentication-tutorial.adoc`. +** Save the file to the root of the `asciidoc` folder in the `quarkus` repository, one level up. +. Set the minimum required header information as outlined in the following example: ++ +[source,asciidoc] +---- +[id="security-basic-authentication-howto"] <1> += Secure a Quarkus application with basic authentication <2> +include::_attributes.adoc[] <3> +:categories: security <4> +---- ++ +<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 the content type, see xref:doc-reference.adoc[Quarkus documentation reference]. +<3> The `_attributes.adoc` include is required to ensure that attributes get resolved, the ToC displays, and content renders in the website portal. +<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 more information about the minimum header requirements, see xref:{doc-guides}/doc-reference.adoc[Quarkus documentation reference]. + +== Retire and redirect an existing Quarkus AsciiDoc source file + +As content evolves, you might want to restructure an existing piece of Quarkus content into one or more content types and retire the existing AsciiDoc source file. + +If you are retiring or renaming a published Quarkus AsciiDoc source file, ensure that the restructure does not break existing bookmarks and links to original content. +Configure a URL redirect in the link:https://github.com/quarkusio/quarkusio.github.io/[Quarkus.io Website] GitHub repository by using the following steps: + +. Switch to the link:https://github.com/quarkusio/quarkusio.github.io/tree/develop/_redirects/guides[quarkusio/quarkusio.github.io] repository, and open the `_redirects/guides` folder. +. Create a redirection file in Markdown format with a filename that matches the original AsciiDoc source filename that you want to retire. +. Add the following contents to the Markdown redirection file: ++ +[source,markdown] +--- +permalink: /guides//index.html // <1> +newUrl: /guides/ // <2> +--- ++ +Where: +<1> Is the name of the original AsciiDoc source file that you are retiring. +<2> Is the name of the AsciiDoc source file that you want to redirect to. + +.Example + +[Attributes] +|=== +|Name of original AsciiDoc source file |Name of file to redirect to| Example pull request + +|`security-getting-started` +|`security-overview-concept` +|link:https://github.com/quarkusio/quarkusio.github.io/pull/1579[PR #1579] + +|=== == Preview and build Quarkus documentation AsciiDoc syntax highlighting and the preview provided by an IDE may be enough for minor documentation changes. -For significant changes or updates to generated configuration documentation, -you should build the `docs` module and view resulting output before submitting your changes for review. +When you make significant changes or updates to generated configuration documentation, build the `docs` module locally and run the Vale linter as outlined below. include::{includes}/compile-quarkus-quickly.adoc[tag=quickly-install-docs] @@ -42,6 +104,8 @@ This will produce: - YAML files containing metadata for all documents individually (`docs/target/indexByFile.yaml`) and grouped by document type (`target/indexByType.yaml`). - YAML files that list metadata errors by file (`docs/target/errorsByFile.yaml`) and by error type (`docs/target/errorsByType.yaml`) +Review the resulting output and fix any issues before you submit your changes in a PR for review. + As you make changes, you can rebuild the `docs` module specifically to update the generated HTML: [source,shell] @@ -101,7 +165,7 @@ See the https://vale.sh/manual/[Vale CLI Manual] for details. === Vale IDE plugins -https://vale.sh/docs/integrations/guide/[Vale IDE integrations] rely on installation the Vale CLI. +https://vale.sh/docs/integrations/guide/[Vale IDE integrations] require the Vale CLI to be installed. Each has it's own configuration requirements. The Visual Studio Code IDE extension, for example, requires two workspace settings: @@ -120,7 +184,7 @@ Submit your proposed changes to the core Quarkus docs by {gh-pull-requests-fork} Reviews for code and documentation have different (but overlapping) participants. To simplify collaborative review, either isolate changes to docs in their own PRs, -or ensure that the PR has a single, focused purpose For example: +or ensure that the PR has a single, focused purpose. For example: - Create a single PR that adds a configuration option for an extension and updates related materials (how-to, reference) to explain the change. - Create a single PR for related changes to a group of documents, some examples: @@ -128,4 +192,14 @@ correcting the usage of a term, correcting a recurring error, or moving common c - If there are extensive code changes and documentation changes, create a separate PR for the documentation changes and include the relationship in the issue description. -Pull requests that contain changes to documentation will have the `area/documentation` label added automatically. \ No newline at end of file +Pull requests that contain changes to documentation will have the `area/documentation` label added automatically. + +== Automatic style checking on the PR diff + +The Vale linter job automatically runs when a PR is created or updated. +If the docs that you contribute do not align with the key style or terminology preferences of our Quarkus community, you will see a suggestion, warning, or error on the diff tab. +To ensure that your content gets approved, fix the linter errors, warnings, and suggestions. + +We welcome your feedback on the Quarkus documentation style guidelines. + +If you disagree with the Vale results, be sure to add the yellow PR label `needs-vale-rule-tweak`. \ No newline at end of file