Merge pull request #280 from miharp/fix-277-relative-docs-links

Use relative links where the text lands in the docs collection

Author: bastelfreak

lib/bolt/config/options.rb

@@ -359,7 +359,7 @@ module Options
           description: "A list of module dependencies for the project. Each dependency is a map of data specifying " \
                        "the module to install. To install the project's module dependencies, run the `bolt module " \
                        "install` command. For more information about specifying modules, see [the " \
-                       "documentation](https://docs.openvoxproject.org/openbolt/latest/bolt_installing_modules.html#manually-specify-modules-in-a-bolt-project).",
+                       "documentation](bolt_installing_modules.md#manually-specify-modules-in-a-bolt-project).",
           type: Array,
           items: {
             type: [Hash, String],

lib/bolt/inventory/options.rb

@@ -84,7 +84,7 @@ module Options
         "plugin_hooks" => {
           description: "Configuration for the Puppet library plugin used to install the " \
                        "Puppet agent on the target. For more information, see " \
-                       "https://docs.openvoxproject.org/openbolt/latest/writing_plugins.html",
+                       "[plugin hooks](writing_plugins.md#plugin-hooks).",
           type: Hash,
           properties: {
             "puppet_library" => {

rakelib/docs.rake

@@ -148,6 +148,16 @@ begin
       $stdout.puts "Generated packaged modules at:\n\t#{filepath}"
     end
 
+    # CLI help text carries full docs URLs, because it is printed to a terminal
+    # where a relative link has nothing to resolve against. Inside the docs
+    # collection the same text must use relative links, so that a locally served
+    # build works offline and a page in an older collection does not silently
+    # follow '/latest/' across a version boundary.
+    docs_url = %r{https://docs\.openvoxproject\.org/openbolt/latest/(\S+?\.html(?:\#[\w-]+)?)}
+    relative_docs_links = lambda do |text|
+      text.gsub(docs_url) { "[#{Regexp.last_match(1)}](#{Regexp.last_match(1)})" }
+    end
+
     desc "Generate markdown docs for Bolt shell commands"
     task :command_reference do
       require 'bolt/bolt_option_parser'
@@ -172,11 +182,11 @@ begin
               short: switch.short.first,
               long: switch.long.first,
               arg: switch.arg,
-              desc: switch.desc.map { |d| d.gsub("<", "&lt;") }.join(" ")
+              desc: relative_docs_links.call(switch.desc.map { |d| d.gsub("<", "&lt;") }.join(" "))
             }
           end
 
-          desc  = matches[:desc].split("\n").map(&:strip).join("\n")
+          desc  = relative_docs_links.call(matches[:desc].split("\n").map(&:strip).join("\n"))
           usage = matches[:usage].strip
 
           @commands[command] = {

schemas/bolt-inventory.schema.json

@@ -1854,7 +1854,7 @@
       ]
     },
     "plugin_hooks": {
-      "description": "Configuration for the Puppet library plugin used to install the Puppet agent on the target. For more information, see https://docs.openvoxproject.org/openbolt/latest/writing_plugins.html",
+      "description": "Configuration for the Puppet library plugin used to install the Puppet agent on the target. For more information, see [plugin hooks](writing_plugins.md#plugin-hooks).",
       "oneOf": [
         {
           "type": "object",

schemas/bolt-project.schema.json

@@ -278,7 +278,7 @@
       }
     },
     "modules": {
-      "description": "A list of module dependencies for the project. Each dependency is a map of data specifying the module to install. To install the project's module dependencies, run the `bolt module install` command. For more information about specifying modules, see [the documentation](https://docs.openvoxproject.org/openbolt/latest/bolt_installing_modules.html#manually-specify-modules-in-a-bolt-project).",
+      "description": "A list of module dependencies for the project. Each dependency is a map of data specifying the module to install. To install the project's module dependencies, run the `bolt module install` command. For more information about specifying modules, see [the documentation](bolt_installing_modules.md#manually-specify-modules-in-a-bolt-project).",
       "type": "array",
       "items": {
         "type": [