From ee0e89906d8ac9fc7d4f0f17fadf446b76465f11 Mon Sep 17 00:00:00 2001 From: Aidan Reilly <74046732+aireilly@users.noreply.github.com> Date: Wed, 17 Apr 2024 10:32:04 +0100 Subject: [PATCH] Clarifying docs --- modules/user-guide/nav.adoc | 1 + .../installing-redhat-style-for-vale.adoc | 74 +++++++++++++++++++ .../user-guide/pages/installing-vale-cli.adoc | 72 +----------------- .../pages/redhat-style-for-vale.adoc | 14 ++-- 4 files changed, 88 insertions(+), 73 deletions(-) create mode 100644 modules/user-guide/pages/installing-redhat-style-for-vale.adoc diff --git a/modules/user-guide/nav.adoc b/modules/user-guide/nav.adoc index 98c7cfebc..d61a32278 100644 --- a/modules/user-guide/nav.adoc +++ b/modules/user-guide/nav.adoc @@ -2,6 +2,7 @@ * xref:introduction.adoc[] * xref:installing-vale-cli.adoc[] +* xref:installing-redhat-style-for-vale.adoc[] * xref:analyze-with-vale.adoc[] ** xref:using-vale-app.adoc[] ** xref:using-vale-cli.adoc[] diff --git a/modules/user-guide/pages/installing-redhat-style-for-vale.adoc b/modules/user-guide/pages/installing-redhat-style-for-vale.adoc new file mode 100644 index 000000000..d447d7f2f --- /dev/null +++ b/modules/user-guide/pages/installing-redhat-style-for-vale.adoc @@ -0,0 +1,74 @@ +// Metadata for Antora +:navtitle: Installing the RedHat style +:keywords: installing-redhat-style-for-vale, antora +:description: Installing the Red Hat style for Vale +// End of metadata for Antora +:_module-type: CONCEPT +[id="installing-redhat-style-for-vale"] += Installing the Red Hat style for Vale globally + +You can install the `RedHat` style for Vale globally. + +[IMPORTANT] +==== +Some product documentation repositories, such as `openshift-docs`, have an existing `.vale.ini` file. +When you run `vale` on content files in the repository directory, the `/.vale.ini` file overrides the `$HOME/.vale.ini` file. For more information, see link:https://vale.sh/docs/topics/config[Vale configuration reference]. + +Run `vale sync` in your project directory to download the Vale rules relative to that project directory. +==== + +.Procedure + +. To use Vale with the `RedHat` package system-wide, create the following `.vale.ini` configuration file in your `$HOME` directory. ++ +.Example .vale.ini +[source,ini] +---- +include::example$vale.ini[] +---- + +. Sync the `RedHat` package to your computer. ++ +[source,console] +---- +$ vale sync +---- ++ +.Example output +[source,terminal] +---- +$ vale sync + SUCCESS Downloaded package 'RedHat' +Downloading packages [1/1] +---- ++ +[TIP] +To get the latest updates, run `vale sync` regularly. + +.Verification + +. Run `vale` against a source file: ++ +[source,console,subs="+quotes,+attributes"] +---- +$ cd ____ +$ vale ____ +---- ++ +.Example output +[source,terminal] +---- +$ vale modules/ztp-creating-the-site-secrets.adoc + + modules/ztp-creating-the-site-secrets.adoc + 10:222 error Use 'Assisted Installer' Vale.Terms + instead of 'assisted + installer'. + 14:13 suggestion 'are referenced' is passive RedHat.PassiveVoice + voice. In general, use active + voice. Consult the style guide + for acceptable use of passive + voice. + +✖ 2 errors, 0 warnings and 1 suggestion in 1 file. +---- diff --git a/modules/user-guide/pages/installing-vale-cli.adoc b/modules/user-guide/pages/installing-vale-cli.adoc index 056a4016f..0628de1cc 100644 --- a/modules/user-guide/pages/installing-vale-cli.adoc +++ b/modules/user-guide/pages/installing-vale-cli.adoc @@ -5,19 +5,14 @@ :page-aliases: end-user-guide:using-vale-cli.adoc, installing-vale-cli-from-zip.adoc // End of metadata for Antora [id="proc_installing-vale-cli"] -= Installing Vale and the RedHat package += Installing Vale -Install the Vale linter and the `RedHat` package to automate reviewing content for style and structure. +Install the Vale linter to begin reviewing content for style and structure. [IMPORTANT] ==== -Vale v3 introduced a breaking change for the Vale vocabulary folder location. -For Vale v3+, if you use a vocabulary with your project, ensure that the vocabulary folder matches this folder structure: - -[source,terminal] ----- -.vale/styles/config/vocabularies/ ----- +If you are working in an established project that has already implemented Vale, you do not need to create a new `vale.ini`. +The project will already have a `vale.ini` configuration. ==== .Prerequisites @@ -58,65 +53,6 @@ $ which vale [NOTE] For other operating systems, see link:https://vale.sh/docs/vale-cli/installation/[Installing Vale]. -. To use Vale with the `RedHat` package system-wide, create the following `.vale.ini` configuration file in your `$HOME` directory. -+ -.Example .vale.ini -[source,ini] ----- -include::example$vale.ini[] ----- -+ -[TIP] -==== -Some product documentation repositories, such as `openshift-docs`, have a `.vale.ini` file. When you run `vale` on content files in the repository directory, the `/.vale.ini` file overrides the `$HOME/.vale.ini` file. For more information, see link:https://vale.sh/docs/topics/config[Vale configuration reference]. -==== - -. Download the `RedHat` package to your computer. -+ -[source,console] ----- -$ vale sync ----- -+ -.Example output -[source,terminal] ----- -$ vale sync - SUCCESS Downloaded package 'RedHat' -Downloading packages [1/1] ----- -+ -[TIP] -To get the latest updates, run `vale sync` regularly. - -.Verification - -. Run `vale` against a source file: -+ -[source,console,subs="+quotes,+attributes"] ----- -$ cd ____ -$ vale ____ ----- -+ -.Example output -[source,terminal] ----- -$ vale modules/ztp-creating-the-site-secrets.adoc - - modules/ztp-creating-the-site-secrets.adoc - 10:222 error Use 'Assisted Installer' Vale.Terms - instead of 'assisted - installer'. - 14:13 suggestion 'are referenced' is passive RedHat.PassiveVoice - voice. In general, use active - voice. Consult the style guide - for acceptable use of passive - voice. - -✖ 2 errors, 0 warnings and 1 suggestion in 1 file. ----- - .Additional resources * xref:understanding-vale-output.adoc[] * xref:defining-a-vale-onboarding-strategy.adoc[] diff --git a/modules/user-guide/pages/redhat-style-for-vale.adoc b/modules/user-guide/pages/redhat-style-for-vale.adoc index 31097283a..d99f3bc4c 100644 --- a/modules/user-guide/pages/redhat-style-for-vale.adoc +++ b/modules/user-guide/pages/redhat-style-for-vale.adoc @@ -15,18 +15,22 @@ The `RedHat` style for Vale consists of language rules suitable for documentatio * link:https://github.com/errata-ai/IBM[Vale-compatible implementation] of link:https://www.ibm.com/developerworks/library/styleguidelines/index.html[_IBM Developer Editorial Style Guide_] * link:{valedict-url}[_{valedict}_] -The xref:contributor-guide:vale-at-red-hat-repository.adoc[] contains the `RedHat` style in the following directory: +[IMPORTANT] +==== +Vale v3 introduced a breaking change for the Vale vocabulary folder location. +For Vale v3+, if you use a vocabulary with your project, ensure that the vocabulary folder matches this folder structure: +[source,terminal] ---- -.vale/styles/RedHat +.vale/styles/config/vocabularies/ ---- +For more information see, link:https://vale.sh/docs/topics/vocab/[Vocabularies]. +==== + [role="_additional-resources"] .Additional resources * xref:installing-vale-cli.adoc[] * xref:using-vale-in-the-ide.adoc[] * xref:using-vale-github-action.adoc[] * xref:adding-vale-configuration-to-a-project.adoc[] - - -