Add readme to the package API

A package can contain a README.md file for the documentation. If there is a README.md file, it is exposed in the API output for easy grabbing by EPM. At the moment the user can't configure the default file which should be used, the convention is the `README.md` file. This file might have an include for further files or data example files. For now we only support the `readme` file for documentation. Later on, we might add links to external documentation / repositories if needed like can be seen here: https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata An example event with a REAME link looks as following: ``` { "name": "example", "title": "Example Integration", "version": "1.0.0", "readme": "/package/example-1.0.0/docs/README.md", "description": "This is the example integration", "type": "integration", "categories": [ "logs", "metrics" ], "requirement": { "kibana": { "version.min": "7.0.0", "version.max": "" } }, "screenshots": [ { "src": "/package/example-1.0.0/img/kibana-iptables.png", "title": "IP Tables Overview dashboard", "size": "1492x1382" }, { "src": "/package/example-1.0.0/img/kibana-iptables-ubiquity.png", "title": "IP Tables Ubiquity Dashboard", "size": "1492x1464", "type": "image/png" } ], "assets": [ "/package/example-1.0.0/index.json", "/package/example-1.0.0/manifest.yml", "/package/example-1.0.0/docs/README.md", "/package/example-1.0.0/img/icon.png", "/package/example-1.0.0/img/kibana-envoyproxy.jpg", "/package/example-1.0.0/elasticsearch/ingest-pipeline/pipeline-entry.json", "/package/example-1.0.0/elasticsearch/ingest-pipeline/pipeline-http.json", "/package/example-1.0.0/elasticsearch/ingest-pipeline/pipeline-json.json", "/package/example-1.0.0/elasticsearch/ingest-pipeline/pipeline-plaintext.json", "/package/example-1.0.0/elasticsearch/ingest-pipeline/pipeline-tcp.json", "/package/example-1.0.0/kibana/dashboard/0c610510-5cbd-11e9-8477-077ec9664dbd.json", "/package/example-1.0.0/kibana/index-pattern/filebeat-*.json", "/package/example-1.0.0/kibana/visualization/0a994af0-5c9d-11e9-8477-077ec9664dbd.json", "/package/example-1.0.0/kibana/visualization/36f872a0-5c03-11e9-85b4-19d0072eb4f2.json", "/package/example-1.0.0/kibana/visualization/38f96190-5c99-11e9-8477-077ec9664dbd.json", "/package/example-1.0.0/kibana/visualization/7e4084e0-5c99-11e9-8477-077ec9664dbd.json", "/package/example-1.0.0/kibana/visualization/80844540-5c97-11e9-8477-077ec9664dbd.json", "/package/example-1.0.0/kibana/visualization/ab48c3f0-5ca6-11e9-8477-077ec9664dbd.json" ] } ```
elastic · Oct 23, 2019 · b174ac8 · b174ac8
1 parent 2b2c26b
commit b174ac8
Show file tree

Hide file tree

Showing 6 changed files with 24 additions and 25 deletions.
diff --git a/dev/generator/main.go b/dev/generator/main.go
@@ -59,7 +59,7 @@ func Build(sourceDir, publicDir string) error {
 	return nil
 }
 
-// CopyPackages copies the files of a package to the public directory
+// CopyPackage copies the files of a package to the public directory
 func CopyPackage(src, dst string) error {
 	fmt.Println(">> Copy package: " + src)
 	os.MkdirAll(dst, 0755)

diff --git a/docs/api/package.json b/docs/api/package.json
@@ -2,6 +2,7 @@
   "name": "example",
   "title": "Example Integration",
   "version": "1.0.0",
+  "readme": "/package/example-1.0.0/docs/README.md",
   "description": "This is the example integration",
   "type": "integration",
   "categories": [
@@ -30,7 +31,7 @@
   "assets": [
     "/package/example-1.0.0/index.json",
     "/package/example-1.0.0/manifest.yml",
-    "/package/example-1.0.0/docs/docs.asciidoc",
+    "/package/example-1.0.0/docs/README.md",
     "/package/example-1.0.0/img/icon.png",
     "/package/example-1.0.0/img/kibana-envoyproxy.jpg",
     "/package/example-1.0.0/elasticsearch/ingest-pipeline/pipeline-entry.json",

diff --git a/testdata/package/example-1.0.0/docs/README.md b/testdata/package/example-1.0.0/docs/README.md
@@ -0,0 +1,3 @@
+# Example readme
+
+This is a readme.
diff --git a/testdata/package/example-1.0.0/docs/docs.asciidoc b/testdata/package/example-1.0.0/docs/docs.asciidoc
diff --git a/testdata/package/example-1.0.0/index.json b/testdata/package/example-1.0.0/index.json
@@ -2,6 +2,7 @@
   "name": "example",
   "title": "Example Integration",
   "version": "1.0.0",
+  "readme": "/package/example-1.0.0/docs/README.md",
   "description": "This is the example integration",
   "type": "integration",
   "categories": [
@@ -30,7 +31,7 @@
   "assets": [
     "/package/example-1.0.0/index.json",
     "/package/example-1.0.0/manifest.yml",
-    "/package/example-1.0.0/docs/docs.asciidoc",
+    "/package/example-1.0.0/docs/README.md",
     "/package/example-1.0.0/img/icon.png",
     "/package/example-1.0.0/img/kibana-envoyproxy.jpg",
     "/package/example-1.0.0/elasticsearch/ingest-pipeline/pipeline-entry.json",

diff --git a/util/package.go b/util/package.go
@@ -28,6 +28,7 @@ type Package struct {
 	Name          string  `yaml:"name" json:"name"`
 	Title         *string `yaml:"title,omitempty" json:"title,omitempty"`
 	Version       string  `yaml:"version" json:"version"`
+	Readme        *string `yaml:"readme,omitempty" json:"readme,omitempty"`
 	versionSemVer semver.Version
 	Description   string      `yaml:"description" json:"description"`
 	Type          string      `yaml:"type" json:"type"`
@@ -110,6 +111,21 @@ func NewPackage(basePath, packageName string) (*Package, error) {
 		return nil, err
 	}
 
+	readmePath := basePath + "/" + packageName + "/docs/README.md"
+	// Check if readme
+	readme, err := os.Stat(readmePath)
+	if err != nil && !os.IsNotExist(err) {
+		return nil, err
+	}
+
+	if readme != nil {
+		if readme.IsDir() {
+			return nil, fmt.Errorf("README.md is a directory")
+		}
+		readmePathShort := "/package/" + packageName + "/docs/README.md"
+		p.Readme = &readmePathShort
+	}
+
 	return p, nil
 }