Add readme to the package API
#128
Conversation
docs/api/package.json
Outdated
| @@ -2,6 +2,7 @@ | |||
| "name": "example", | |||
| "title": "Example Integration", | |||
| "version": "1.0.0", | |||
| "readme": "/docs/README.md", | |||
There was a problem hiding this comment.
@neptunian Would that work as an API endpoint? This entry exists, if there is a readme. If there is no README.md file, this entry does not exist and we should fall back to the description.
I wonder if we should call this entry differently like docs_index or similar?
There was a problem hiding this comment.
Personally, I like readme for this. We've currently got:
name: essentially an id (e.g. postgres)
title: Short stylized string representation of the package (e.g. PostgreSQL)
description: medium(? not sure how to quantify) length text. Used in our cards for results
We need something for "Long description (pages in length is fine) that allows stylized markup (specifically Markdown)". I think readme works for this.
Authors might reasonably expect docs or documentation to point to their docs site or a page which uses a layout like this image which is common. We wouldn't want something like that on the details page, but it's very common for projects to use this style in documentation.
Looking at the PostgreSQL 12 docs I don't think we'd want something like this in the details view
The PostgreSQL README isn't very attractive either, but I think it's more useful and appropriate for the details page.
Begin README paste:
PostgreSQL Database Management System
This directory contains the source code distribution of the PostgreSQL
database management system.
PostgreSQL is an advanced object-relational database management system
that supports an extended subset of the SQL standard, including
transactions, foreign keys, subqueries, triggers, user-defined types
and functions. This distribution also contains C language bindings.
PostgreSQL has many language interfaces, many of which are listed here:
https://www.postgresql.org/download
See the file INSTALL for instructions on how to build and install
PostgreSQL. That file also lists supported operating systems and
hardware platforms and contains information regarding any other
software packages that are required to build or run the PostgreSQL
system. Copyright and license information can be found in the
file COPYRIGHT. A comprehensive documentation set is included in this
distribution; it can be read as described in the installation
instructions.
The latest version of this software may be obtained at
https://www.postgresql.org/download/. For more information look at our
web site located at https://www.postgresql.org/.
End README paste
I realize we not using these repo files specifically, but I think it points to a convention of what people expect in a README and that aligns well with what we're putting in that section of the details view.
There's also precedent in Rust's Cargo.toml manifest format. From their [package] section
# A short blurb about the package. This is not rendered in any format when
# uploaded to crates.io (aka this is not markdown).
description = "..."
# These URLs point to more information about the package. These are
# intended to be webviews of the relevant data, not necessarily compatible
# with VCS tools and the like.
documentation = "..."
homepage = "..."
repository = "..."
# This points to a file under the package root (relative to this `Cargo.toml`).
# The contents of this file are stored and indexed in the registry.
# crates.io will render this file and place the result on the crate's page.
readme = "..."
|
Think I'd agree with @jfsiii here. Docs seems like it might be something more extensive rather than pointing to a single markdown file. Although if all the documentation that's going to exist or be needed are in these small readme files then docs would make sense as well. |
|
Lots of inspiration we can take from the manifest you linked @jfsiii https://doc.rust-lang.org/cargo/reference/manifest.html I think the current state we are is the README.md file. There will be some external links to our docs pages for things that don't fit into the readme. If we really grow to the size of documentation that postgresql has, we will probably need The main difference for the README on our side for now is, that a README can link further files. So my suggestion is we stick for now with |
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" ] } ```
| @@ -2,6 +2,7 @@ | |||
| "name": "example", | |||
| "title": "Example Integration", | |||
| "version": "1.0.0", | |||
| "readme": "/package/example-1.0.0/docs/README.md", | |||
There was a problem hiding this comment.
@neptunian I made a change to the PR that this is now the full path like for all the other assets. Let me know what works best on your end.
There was a problem hiding this comment.
ah, i missed this previously. this is preferable.
|
@neptunian @skh @jfsiii Related to this change, we discussed if a package can exist without a description. The current answer is no, as each package is validate during startup and having a description is a requirement: https://github.com/elastic/integrations-registry/blob/master/util/package.go#L226 |
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.mdfile. This file might have an include for further files or data example files.For now we only support the
readmefile 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-metadataAn example event with a REAME link looks as following: