-
Couldn't load subscription status.
- Fork 128
Add docs template language to elastic-package create package
#954
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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. | ||
| <!-- 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}. --> | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 It may be good to include them also here. |
||
| <!-- Optional --> | ||
| <!-- #### Example | ||
| An example event for ` + "`{data stream name}`" + ` looks as following: | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There are also helpers to include sample events, see here: https://github.com/elastic/integrations/blob/8d2ecab10823e2b54ea7ffa3e4252b9eaba597a8/packages/apache/_dev/build/docs/README.md?plain=1#L50 |
||
| {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} -->` | ||
There was a problem hiding this comment.
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:
To be used in integrations repository, currently there are still some requirements pending (on-going):
elastic-packagewith the changes mentioned above.There was a problem hiding this comment.
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
urlhere, 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.There was a problem hiding this comment.
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.