Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 82 additions & 3 deletions internal/packages/archetype/package_docs_readme.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,87 @@

package archetype

const packageDocsReadme = `# {{.Manifest.Title}}
const packageDocsReadme = `<!-- Use this template language as a starting point, replacing {placeholder text} with details about the integration. -->
<!-- Find more detailed documentation guidelines in https://github.com/elastic/integrations/blob/main/docs/documentation_guidelines.md -->
This is a new integration created using the [elastic-package](https://github.com/elastic/elastic-package) tool.
# {{.Manifest.Title}}
Consider using the README template file ` + "`_dev/build/docs/README.md`" + `to generate a list of exported fields or include a sample event.`
<!-- The {{.Manifest.Title}} integration allows you to monitor {name of service}. {name of service} is {describe service}.
Use the {{.Manifest.Title}} integration to {purpose}. Then visualize that data in Kibana, create alerts to notify you if something goes wrong, and reference {data stream type} when troubleshooting an issue.
For example, if you wanted to {sample use case} you could {action}. Then you can {visualize|alert|troubleshoot} by {action}. -->
## Data streams
<!-- The {{.Manifest.Title}} integration collects {one|two} type{s} of data streams: {logs and/or metrics}. -->
<!-- If applicable -->
<!-- **Logs** help you keep a record of events happening in {service}.
Log data streams collected by the {name} integration include {sample data stream(s)} and more. See more details in the [Logs](#logs-reference). -->
<!-- If applicable -->
<!-- **Metrics** give you insight into the state of {service}.
Metric data streams collected by the {name} integration include {sample data stream(s)} and more. See more details in the [Metrics](#metrics-reference). -->
<!-- Optional: Any additional notes on data streams -->
## Requirements
You need Elasticsearch for storing and searching your data and Kibana for visualizing and managing it.
You can use our hosted Elasticsearch Service on Elastic Cloud, which is recommended, or self-manage the Elastic Stack on your own hardware.
<!--
Optional: Other requirements including:
* System compatibility
* Supported versions of third-party products
* Permissions needed
* Anything else that could block a user from successfully using the integration
-->
## Setup
<!-- Any prerequisite instructions -->
For step-by-step instructions on how to set up an integration, see the
[Getting started](https://www.elastic.co/guide/en/welcome-to-elastic/current/getting-started-observability.html) guide.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A branch has been just merged that introduces a new helper in elastic-package to render this kind of links to Elastic documentation guides (links like https://www.elastic.co/guide/*).

With that PR, this link could be replaced by the "url" helper:

{{ url "getting-started-observability" "Getting started" }} guide.

To be used in integrations repository, currently there are still some requirements pending (on-going):

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point, but if we use url here, we should also probably add support for the creation of the links map file when it doesn't exist, as this command can be used on any place. Let's leave this for a follow up.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's true, let's leave it as it is 👍.
As you mentioned at this point it is not mandatory that the links definitions file exist.

<!-- Additional set up instructions -->
<!-- If applicable -->
<!-- ## Logs reference -->
<!-- Repeat for each data stream of the current type -->
<!-- ### {Data stream name}
The ` + "`{data stream name}`" + ` data stream provides events from {source} of the following types: {list types}. -->
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Btw, there are helpers to generate documentation of fields, see for example in the template for the README of the Apache integration: https://github.com/elastic/integrations/blob/8d2ecab10823e2b54ea7ffa3e4252b9eaba597a8/packages/apache/_dev/build/docs/README.md?plain=1#L17

{{ fields "access" }}

It may be good to include them also here.

<!-- Optional -->
<!-- #### Example
An example event for ` + "`{data stream name}`" + ` looks as following:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

{code block with example} -->
<!-- #### Exported fields
{insert table} -->
<!-- If applicable -->
<!-- ## Metrics reference -->
<!-- Repeat for each data stream of the current type -->
<!-- ### {Data stream name}
The ` + "`{data stream name}`" + ` data stream provides events from {source} of the following types: {list types}. -->
<!-- Optional -->
<!-- #### Example
An example event for ` + "`{data stream name}`" + ` looks as following:
{code block with example} -->
<!-- #### Exported fields
{insert table} -->`