Avoid hardcoded links in READMEs (#938)

Added the option to add a YAML  file containing links definitions. These definitions
will be used to render "_dev/build/docs/*.md" files that use the new placeholder "url".
The path to this file can be defined using the ELASTIC_PACKAGE_LINKS_FILE_PATH
env var. By default, if that env var is not defined, it is looked at the root of the
repository a file named "links_table.yml".
Updated documentation about README to include this new "url" placeholder.

Author: mrodm

cmd/profiles.go

@@ -16,6 +16,7 @@ import (
 
 	"github.com/elastic/elastic-package/internal/cobraext"
 	"github.com/elastic/elastic-package/internal/configuration/locations"
+	"github.com/elastic/elastic-package/internal/environment"
 	"github.com/elastic/elastic-package/internal/profile"
 )
 
@@ -26,7 +27,7 @@ const jsonFormat = "json"
 const tableFormat = "table"
 
 // profileNameEnvVar is the name of the environment variable to set the default profile
-const profileNameEnvVar = "ELASTIC_PACKAGE_PROFILE"
+var profileNameEnvVar = environment.WithElasticPackagePrefix("PROFILE")
 
 func setupProfilesCommand() *cobraext.Command {
 	profilesLongDescription := `Use this command to add, remove, and manage multiple config profiles.

docs/howto/add_package_readme.md

@@ -17,6 +17,7 @@ Files in `_dev/build/docs/*.md` follow Markdown syntax and they are rendered usi
 In addition to Markdown syntax, there are some additional placeholders that can be used in order to help
 to complete the information shown to the user.
 
+
 ## Placeholders
 
 List of placeholders that can be used in the Markdown templates:
@@ -81,3 +82,62 @@ List of placeholders that can be used in the Markdown templates:
       | data_stream.type | Data stream type. | constant_keyword |  |  |
       ...
       ```
+- `url <link_key>`: this placeholder is replaced by the URL defined in the `links_table.yml` file.
+    - Example of usage:
+      ```
+      Check {{ url "foo" }}
+      ```
+    - Let's assume that there exists a file `links_table.yml` with these contents:
+      ```
+      links:
+        foo: http://url.com.test
+        help: http://other.url.com/help
+      ```
+    - Rendered output:
+      ```
+      Check http://url.com.test
+      ```
+    - Requirements:
+        - It is needed to define a file with the links definitions. More information [in this section](#requirements)
+- `url <link_key> <link_text>`: this placeholder is replaced by the URL defined in the `links_table.yml` file and it creates a
+  markdown link as `[link_text](url)`
+    - Example of usage:
+      ```
+      Check {{ url "help" "help guide" }}
+      ```
+    - Let's assume that there exists a file `links_table.yml` with these contents:
+      ```
+      links:
+        foo: http://url.com.test
+        help: http://other.url.com/help
+      ```
+    - Rendered output:
+      ```
+      Check [help guide](http://other.url.com/help)
+      ```
+    - Requirements:
+        - It is needed to define a file with the links definitions. More information [in this section](#requirements)
+
+## Requirements
+
+### Links definitions file
+
+In order to be able to use `url` placeholder, links must be defined in a file.
+
+This file by default is located at the root of the repository with the name `links_table.yml`.
+It can be overwritten by setting the environment variable `ELASTIC_PACKAGE_LINKS_FILE_PATH` with
+the path to corresponding YAML file.
+
+The format of this file must be:
+```
+links:
+  <key_1>: <url_1>
+  <key_2>: <url_2>
+  <key_3>: <url_3>
+```
+
+As these links are rendered in building time (running `elastic-package build` command), there are some
+considerations that developers need to take into account:
+- packages will be built using always the links defined in the given file (e.g. `links_table.yml`).
+- any needed change in links requires that a new version of the package must be published to update the
+  corresponding README file.

internal/builder/packages.go

@@ -267,7 +267,7 @@ func copyLicenseTextFile(licensePath string) error {
 }
 
 func createBuildDirectory(dirs ...string) (string, error) {
-	dir, err := findRepositoryRootDirectory()
+	dir, err := files.FindRepositoryRootDirectory()
 	if errors.Is(err, os.ErrNotExist) {
 		return "", errors.New("package can be only built inside of a Git repository (.git folder is used as reference point)")
 	}
@@ -287,40 +287,17 @@ func createBuildDirectory(dirs ...string) (string, error) {
 	return buildDir, nil
 }
 
-func findRepositoryRootDirectory() (string, error) {
-	workDir, err := os.Getwd()
-	if err != nil {
-		return "", errors.Wrap(err, "locating working directory failed")
-	}
-
-	dir := workDir
-	for dir != "." {
-		path := filepath.Join(dir, ".git")
-		fileInfo, err := os.Stat(path)
-		if err == nil && fileInfo.IsDir() {
-			return dir, nil
-		}
-
-		if dir == "/" {
-			break
-		}
-		dir = filepath.Dir(dir)
-	}
-
-	return "", os.ErrNotExist
-}
-
 func findRepositoryLicense() (string, error) {
-	dir, err := findRepositoryRootDirectory()
+	dir, err := files.FindRepositoryRootDirectory()
 	if err != nil {
 		return "", err
 	}
 
-	sourceLicensePath := filepath.Join(dir, licenseTextFileName)
-	_, err = os.Stat(sourceLicensePath)
+	sourceFileName := filepath.Join(dir, licenseTextFileName)
+	_, err = os.Stat(sourceFileName)
 	if err != nil {
 		return "", err
 	}
 
-	return sourceLicensePath, nil
+	return sourceFileName, nil
 }

internal/configuration/locations/locations.go

@@ -10,12 +10,11 @@ import (
 	"path/filepath"
 
 	"github.com/pkg/errors"
+
+	"github.com/elastic/elastic-package/internal/environment"
 )
 
 const (
-	// elasticPackageDataHome is the name of the environment variable used to override data folder for elastic-package
-	elasticPackageDataHome = "ELASTIC_PACKAGE_DATA_HOME"
-
 	elasticPackageDir = ".elastic-package"
 	stackDir          = "stack"
 	packagesDir       = "development"
@@ -32,6 +31,9 @@ const (
 )
 
 var (
+	// elasticPackageDataHome is the name of the environment variable used to override data folder for elastic-package
+	elasticPackageDataHome = environment.WithElasticPackagePrefix("DATA_HOME")
+
 	serviceLogsDir               = filepath.Join(temporaryDir, "service_logs")
 	kubernetesDeployerDir        = filepath.Join(deployerDir, "kubernetes")
 	terraformDeployerDir         = filepath.Join(deployerDir, "terraform")

internal/docs/links_map.go

@@ -0,0 +1,117 @@
+// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+// or more contributor license agreements. Licensed under the Elastic License;
+// you may not use this file except in compliance with the Elastic License.
+
+package docs
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/pkg/errors"
+	"gopkg.in/yaml.v3"
+
+	"github.com/elastic/elastic-package/internal/environment"
+	"github.com/elastic/elastic-package/internal/files"
+	"github.com/elastic/elastic-package/internal/logger"
+)
+
+const linksMapFileNameDefault = "links_table.yml"
+
+var linksMapFilePathEnvVar = environment.WithElasticPackagePrefix("LINKS_FILE_PATH")
+
+type linkMap struct {
+	Links map[string]string `yaml:"links"`
+}
+
+type linkOptions struct {
+	caption string
+}
+
+func newLinkMap() linkMap {
+	var links linkMap
+	links.Links = make(map[string]string)
+	return links
+}
+
+func (l linkMap) Get(key string) (string, error) {
+	if url, ok := l.Links[key]; ok {
+		return url, nil
+	}
+	return "", errors.Errorf("link key not found: %s", key)
+}
+
+func (l linkMap) Add(key, value string) error {
+	if _, ok := l.Links[key]; ok {
+		return errors.Errorf("link key already present: %s", key)
+	}
+	l.Links[key] = value
+	return nil
+}
+
+func readLinksMap() (linkMap, error) {
+	linksFilePath, err := linksDefinitionsFilePath()
+	if err != nil {
+		return linkMap{}, errors.Wrap(err, "locating links file failed")
+	}
+
+	links := newLinkMap()
+	if linksFilePath == "" {
+		return links, nil
+	}
+
+	logger.Debugf("Using links definitions file: %s", linksFilePath)
+	contents, err := os.ReadFile(linksFilePath)
+	if err != nil {
+		return linkMap{}, errors.Wrapf(err, "readfile failed (path: %s)", linksFilePath)
+	}
+
+	err = yaml.Unmarshal(contents, &links)
+	if err != nil {
+		return linkMap{}, err
+	}
+
+	return links, nil
+}
+
+func (l linkMap) RenderLink(key string, options linkOptions) (string, error) {
+	url, err := l.Get(key)
+	if err != nil {
+		return "", err
+	}
+	if options.caption != "" {
+		url = fmt.Sprintf("[%s](%s)", options.caption, url)
+	}
+	return url, nil
+}
+
+// linksDefinitionsFilePath returns the path where links definitions are located or empty string if the file does not exist.
+// If linksMapFilePathEnvVar is defined, it returns the value of that env var.
+func linksDefinitionsFilePath() (string, error) {
+	var err error
+	linksFilePath, ok := os.LookupEnv(linksMapFilePathEnvVar)
+	if ok {
+		_, err = os.Stat(linksFilePath)
+		if err != nil {
+			// if env var is defined, file must exist
+			return "", fmt.Errorf("links definitions file set with %s doesn't exist: %s", linksMapFilePathEnvVar, linksFilePath)
+		}
+		return linksFilePath, nil
+	}
+
+	dir, err := files.FindRepositoryRootDirectory()
+	if err != nil {
+		return "", err
+	}
+
+	linksFilePath = filepath.Join(dir, linksMapFileNameDefault)
+	_, err = os.Stat(linksFilePath)
+	if err != nil {
+		logger.Debugf("links definitions default file doesn't exist: %s", linksFilePath)
+		return "", nil
+	}
+
+	return linksFilePath, nil
+
+}