Merge pull request #357 from miharp/cleanup/markdownlint-openvox-manual

Finish _openvox_8x markdownlint cleanup and enforce repo-wide

Author: tuxmea

.github/workflows/markdownlint.yml

@@ -16,71 +16,20 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-        with:
-          fetch-depth: 0  # required to resolve base.sha for PR diff comparison
-      - name: Find changed Markdown files
-        id: changed-markdown
+      - name: List tracked Markdown files
+        id: tracked-markdown
         shell: bash
+        # Lint git-tracked files only. This lints the canonical versioned dirs
+        # once and skips the `_latest` symlinks (git stores them as single
+        # symlink entries, so a filesystem glob would double-lint their targets).
+        # It also excludes generated reference docs, which are gitignored.
         run: |
-          case "${GITHUB_EVENT_NAME}" in
-            pull_request)
-              base_sha="${{ github.event.pull_request.base.sha }}"
-              head_sha="${GITHUB_SHA}"
-              ;;
-            push)
-              base_sha="${{ github.event.before }}"
-              head_sha="${GITHUB_SHA}"
-              ;;
-            *)
-              # workflow_dispatch: lints only files changed in the most recent commit, not the full branch
-              # || true handles initial commits with no parent
-              base_sha="$(git rev-parse "${GITHUB_SHA}^" 2>/dev/null || true)"
-              head_sha="${GITHUB_SHA}"
-              ;;
-          esac
-
-          if [[ -z "${base_sha}" || "${base_sha}" =~ ^0+$ ]]; then
-            base_sha="$(git rev-list --max-parents=0 "${head_sha}")"
-          fi
-
-          git diff --name-only --diff-filter=A    "${base_sha}" "${head_sha}" -- '*.md' '*.markdown' > added-markdown-files.txt
-          git diff --name-only --diff-filter=CMRT "${base_sha}" "${head_sha}" -- '*.md' '*.markdown' > modified-markdown-files.txt
-
-          if [[ -s added-markdown-files.txt ]]; then
-            echo "has_added=true" >> "${GITHUB_OUTPUT}"
-            {
-              echo 'added_files<<EOF'
-              cat added-markdown-files.txt
-              echo 'EOF'
-            } >> "${GITHUB_OUTPUT}"
-          else
-            echo "has_added=false" >> "${GITHUB_OUTPUT}"
-          fi
-
-          if [[ -s modified-markdown-files.txt ]]; then
-            echo "has_modified=true" >> "${GITHUB_OUTPUT}"
-            {
-              echo 'modified_files<<EOF'
-              cat modified-markdown-files.txt
-              echo 'EOF'
-            } >> "${GITHUB_OUTPUT}"
-          else
-            echo "has_modified=false" >> "${GITHUB_OUTPUT}"
-          fi
-
-      - name: No changed Markdown files
-        if: steps.changed-markdown.outputs.has_added != 'true' && steps.changed-markdown.outputs.has_modified != 'true'
-        run: echo "No changed Markdown files to lint."
-
-      - name: Lint new Markdown files (enforced)
-        uses: DavidAnson/markdownlint-cli2-action@v23
-        if: steps.changed-markdown.outputs.has_added == 'true'
-        with:
-          globs: ${{ steps.changed-markdown.outputs.added_files }}
-
-      - name: Lint modified Markdown files (advisory)
+          {
+            echo 'files<<EOF'
+            git ls-files '*.md' '*.markdown'
+            echo 'EOF'
+          } >> "${GITHUB_OUTPUT}"
+      - name: Lint tracked Markdown files
         uses: DavidAnson/markdownlint-cli2-action@v23
-        if: steps.changed-markdown.outputs.has_modified == 'true'
-        continue-on-error: true
         with:
-          globs: ${{ steps.changed-markdown.outputs.modified_files }}
+          globs: ${{ steps.tracked-markdown.outputs.files }}

docs/_openvox_8x/_environment_conf_settings.md

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD041 -->
 In this version of Puppet, the environment.conf file is only allowed to override five settings:
 
 - `modulepath`

docs/_openvox_8x/_hiera.yaml_v5.md

@@ -1,4 +1,5 @@
-``` yaml
+<!-- markdownlint-disable MD041 -->
+```yaml
 ---
 version: 5
 defaults:  # Used for any hierarchy level that omits these keys.

docs/_openvox_8x/_hiera_context_object.md

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD041 -->
 ## The `Puppet::LookupContext` object
 
 To support caching and other needs, Hiera provides backends a special `Puppet::LookupContext` object, which has several methods you can call for various effects.
@@ -24,7 +25,7 @@ The following methods are available:
 
 ### `not_found()`
 
-[method_not]: #notfound
+[method_not]: #not_found
 
 Tells Hiera to move on to the next data source. Call this method when your function can't find a value for a given lookup. **This method does not return.**
 
@@ -44,13 +45,13 @@ In `lookup_key` and `data_dig` backends, you **must** call this method if you wa
 
 ### `environment_name()`
 
-[method_env]: #environmentname
+[method_env]: #environment_name
 
 Returns the name of the environment whose hiera.yaml called the function. Returns `undef` (in Puppet) or `nil` (in Ruby) if the function was called by the global or module layer.
 
 ### `module_name()`
 
-[method_module]: #modulename
+[method_module]: #module_name
 
 Returns the name of the module whose hiera.yaml called the function. Returns `undef` (in Puppet) or `nil` (in Ruby) if the function was called by the global or environment layer.
 
@@ -62,7 +63,9 @@ Caches a value, in a per-data-source private cache; also returns the cached valu
 
 On future lookups in this data source, you can retrieve values with `cached_value(key)`. Cached values are immutable, but you can replace the value for an existing key. Cache keys can be anything valid as a key for a Ruby hash. (Notably, this means you can use `nil` as a key.)
 
-For example, on its first invocation for a given YAML file, the built-in `eyaml_lookup_key` backend reads the whole file and caches it, and then decrypts only the specific value that was requested. On subsequent lookups into that file, it gets the encrypted value from the cache instead of reading the file from disk again. It also caches decrypted values, so that it won't have to decrypt again if the same key is looked up repeatedly.
+For example, on its first invocation for a given YAML file, the built-in `eyaml_lookup_key` backend reads the whole file and caches it, and then decrypts only the specific value that was requested.
+On subsequent lookups into that file, it gets the encrypted value from the cache instead of reading the file from disk again.
+It also caches decrypted values, so that it won't have to decrypt again if the same key is looked up repeatedly.
 
 The cache is also useful for storing session keys or connection objects for backends that access a network service.
 
@@ -77,39 +80,39 @@ If any inputs to a function change (for example, a path interpolates a local var
 
 ### `cache_all(hash)`
 
-[method_cache_all]: #cacheallhash
+[method_cache_all]: #cache_allhash
 
 Caches all the key/value pairs from a given hash; returns `undef` (in Puppet) or `nil` (in Ruby).
 
 ### `cached_value(key)`
 
-[method_cached]: #cachedvaluekey
+[method_cached]: #cached_valuekey
 
 Returns a previously cached value from the per-data-source private cache. Returns `nil` or `undef` if no value with this name has been cached. See [`cache(key, value)`][method_cache] above for more info about how the cache works.
 
 ### `cache_has_key(key)`
 
-[method_haskey]: #cachehaskeykey
+[method_haskey]: #cache_has_keykey
 
 Checks whether the cache has a value for a given key yet. Returns `true` or `false`.
 
 ### `cached_entries()`
 
-[method_allcached]: #cachedentries
+[method_allcached]: #cached_entries
 
 Returns everything in the per-data-source cache, as an iterable object. Note that this iterable object isn't a hash; if you want a hash, you can use `Hash($context.all_cached())` (in the Puppet language) or `Hash[context.all_cached()]` (in Ruby).
 
 ### `cached_file_data(path) {|content| ...}`
 
-[method_cached_file]: #cachedfiledatapath-content-
+[method_cached_file]: #cached_file_datapath-content-
 
 > **Note:** The header above uses Ruby's block syntax. To call this method in the Puppet language, you would use `cached_file_data(path) |content| { ... }`.
 
 For best performance, use this method to read files in Hiera backends.
 
 Returns the content of the specified file, as a string. If an optional block is provided, it passes the content to the block and returns the block's return value. For example, the built-in JSON backend uses a block to parse JSON and return a hash:
 
-``` ruby
+```ruby
     context.cached_file_data(path) do |content|
       begin
         JSON.parse(content)

docs/_openvox_8x/_hiera_options_hash.md

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD041 -->
 ### The options hash
 
 Hierarchy levels are configured in [hiera.yaml](./hiera_config_yaml_5.html). When calling a backend function, Hiera passes a modified version of that configuration as a hash.
@@ -6,13 +7,13 @@ The options hash contains the following keys:
 
 * `path` --- The absolute path to a file on disk. Only present if the user set one of the `path`, `paths`, `glob`, or `globs` settings. Hiera ensures the file exists before passing it to the function.
 
-  > **Note:** If your backend uses data files, use the context object's [`cached_file_data` method][method_cached_file] to read them.
+  > **Note:** If your backend uses data files, use the context object's [`cached_file_data` method][method_cached_file] to read them. <!-- markdownlint-disable-line MD052 -->
 * `uri` --- A URI that your function can use to locate a data source. Only present if the user set `uri` or `uris`. Hiera doesn't verify the URI before passing it to the function.
 * Every key from the hierarchy level's `options` setting. In your documentation, make sure to list any options your backend requires or accepts. Note that the `path` and `uri` keys are reserved.
 
 For example: this hierarchy level in hiera.yaml...
 
-``` yaml
+```yaml
   - name: "Secret data: per-node, per-datacenter, common"
     lookup_key: eyaml_lookup_key # eyaml backend
     datadir: data
@@ -27,7 +28,7 @@ For example: this hierarchy level in hiera.yaml...
 
 ...would result in several different options hashes (depending on the current node's facts, whether the files exist, etc.), but they would all resemble the following:
 
-``` ruby
+```ruby
 {
   'path' => '/etc/puppetlabs/code/environments/production/data/secrets/nodes/web01.example.com.eyaml',
   'pkcs7_private_key' => '/etc/puppetlabs/puppet/eyaml/private_key.pkcs7.pem',

docs/_openvox_8x/_naming_variables.md

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD041 -->
 [qualified_var]: ./lang_variables.html#accessing-out-of-scope-variables
 
 Variable names begin with a `$` (dollar sign) and are case-sensitive.

docs/_openvox_8x/_nodename_certname.md

@@ -1,8 +1,10 @@
+<!-- markdownlint-disable MD041 -->
 [node_name_fact]: ./configuration.html#node_name_fact
 [node_name_value]: ./configuration.html#node_name_value
 
 > #### Note on Non-Certname Node Names
 >
-> Although it's possible to set something other than the [certname][] as the node name (using either the [`node_name_fact`][node_name_fact] or [`node_name_value`][node_name_value] setting), we don't generally recommend it. It allows you to re-use one node certificate for many nodes, but it reduces security, makes it harder to reliably identify nodes, and can interfere with other features.
+> Although it's possible to set something other than the [certname][] as the node name (using either the [`node_name_fact`][node_name_fact] or [`node_name_value`][node_name_value] setting), we don't generally recommend it. <!-- markdownlint-disable-line MD052 -->
+> It allows you to re-use one node certificate for many nodes, but it reduces security, makes it harder to reliably identify nodes, and can interfere with other features.
 >
 > Setting a non-certname node name is **not officially supported** in Puppet Enterprise.

docs/_openvox_8x/_puppet_types_to_ruby_types.md

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD041 -->
 [boolean]: ./lang_data_boolean.html
 [undef]: ./lang_data_undef.html
 [string]: ./lang_data_string.html

docs/_openvox_8x/_registered_oids.md

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD041 -->
 The "ppRegCertExt" OID range contains the following OIDs:
 
 Numeric ID              | Short Name         | Descriptive Name

docs/_openvox_8x/bgtm.md

@@ -27,7 +27,9 @@ To help plan your module appropriately, consider:
 
 It is standard practice for Puppet users to have 200 or more modules in an environment. Simple is better. Each module in your environment should contain related resources that enable it to accomplish a task. Create multiple modules for more complex needs. The practice of having many small, focused modules promotes code reuse and turns modules into building blocks.
 
-As an example, let's take a look at the [`puppetlabs-puppetdb`](https://forge.puppet.com/puppetlabs/puppetdb) module. This module deals solely with the the setup, configuration, and management of PuppetDB. However, PuppetDB stores its data in a PostgreSQL database. Rather than having the module manage PostgreSQL, the author included the [`puppetlabs-postgresql`](https://forge.puppet.com/puppetlabs/postgresql) module as a dependency, leveraging the postgresql module's classes and resources to build out the right configuration for PuppetDB. Similarly, the `puppetdb-module` needs to manipulate the `puppet.conf` file in order to operate PuppetDB. Instead of having the `puppetdb-module` handle `puppet.conf` changes internally, the author used the [`puppetlabs-inifile`](https://forge.puppet.com/puppetlabs/inifile) module to enable `puppetlabs-puppetdb` to make only the required edits to `puppet.conf`.
+As an example, let's take a look at the [`puppetlabs-puppetdb`](https://forge.puppet.com/puppetlabs/puppetdb) module. This module deals solely with the the setup, configuration, and management of PuppetDB. However, PuppetDB stores its data in a PostgreSQL database.
+Rather than having the module manage PostgreSQL, the author included the [`puppetlabs-postgresql`](https://forge.puppet.com/puppetlabs/postgresql) module as a dependency, leveraging the postgresql module's classes and resources to build out the right configuration for PuppetDB.
+Similarly, the `puppetdb-module` needs to manipulate the `puppet.conf` file in order to operate PuppetDB. Instead of having the `puppetdb-module` handle `puppet.conf` changes internally, the author used the [`puppetlabs-inifile`](https://forge.puppet.com/puppetlabs/inifile) module to enable `puppetlabs-puppetdb` to make only the required edits to `puppet.conf`.
 
 ## Structuring your module
 
@@ -54,7 +56,8 @@ In terms of class structure we recommend the following (more detail below):
 
 #### `module`
 
-The main class of any module must share the name of the module and be located in the `init.pp` file. The name and location of the main module class is extremely important, as it guides the [autoloader](./lang_namespaces.html#autoloader-behavior) behavior. The main class of a module is its interface point and ought to be the only parameterized class if possible. Limiting the parameterized classes to just the main class allows you to control usage of the entire module with the inclusion of a single class. This class should provide sensible defaults so that a user can get going with `include module`.
+The main class of any module must share the name of the module and be located in the `init.pp` file. The name and location of the main module class is extremely important, as it guides the [autoloader](./lang_namespaces.html#autoloader-behavior) behavior.
+The main class of a module is its interface point and ought to be the only parameterized class if possible. Limiting the parameterized classes to just the main class allows you to control usage of the entire module with the inclusion of a single class. This class should provide sensible defaults so that a user can get going with `include module`.
 
 For instance, the main `ntp` class in the `ntp` module looks like this:
 
@@ -199,7 +202,8 @@ To maximize the usability of your module, make it flexible by adding parameters.
 
 You must not hardcode data in your modules, and having more parameters is the best alternative. Hardcoding data in your module makes it inflexible, and means your module requires manifest changes to be used in even slightly different circumstances.
 
-Avoid adding parameters that allow you to override templates. When your parameters allow  template overrides, users can override your template with a custom template that contains additional hardcoded parameters. Hardcoded parameters in templates inhibits flexibility over time. It is far better to create more parameters and then modify the original template, or have a parameter which accepts an arbitrary chunk of text added to the template, than it is to override the template with a customized one.
+Avoid adding parameters that allow you to override templates. When your parameters allow  template overrides, users can override your template with a custom template that contains additional hardcoded parameters.
+Hardcoded parameters in templates inhibits flexibility over time. It is far better to create more parameters and then modify the original template, or have a parameter which accepts an arbitrary chunk of text added to the template, than it is to override the template with a customized one.
 
 For an example of a module that capitalizes on offering many parameters, please see [puppetlabs-apache](https://forge.puppet.com/puppetlabs/apache).
 
@@ -313,7 +317,8 @@ We encourage you to publish your modules on the [Puppet Forge](https://forge.pup
 
 Sharing your modules allows other users to write improvements to the modules you make available and contribute them back to you, effectively giving you free improvements to your modules.
 
-Additionally, publishing your modules to the Forge helps foster community among Puppet users, and allows other Puppet community members to download and use your module. If the Puppet community routinely releases and iterates on modules on the Forge, the quality of available modules increases dramatically and gives you access to more modules to download and modify for your own purposes. Details on how to publish modules to the Forge can be found in the [module publishing guide](./modules_publishing.html).
+Additionally, publishing your modules to the Forge helps foster community among Puppet users, and allows other Puppet community members to download and use your module.
+If the Puppet community routinely releases and iterates on modules on the Forge, the quality of available modules increases dramatically and gives you access to more modules to download and modify for your own purposes. Details on how to publish modules to the Forge can be found in the [module publishing guide](./modules_publishing.html).
 
 ## Community Resources