Add docs template language to `elastic-package create package` #954

colleenmcginnis · 2022-08-30T22:43:05Z

Closes #880

In elastic/integrations#3433, we added more detailed documentation guidelines for integrations (including template language). In that PR @jsoriano suggested:

elastic-package create package can be used to create an initial scaffolding for new packages, as a follow up we could apply these recommendations in the templates there.

@jsoriano pointed me to this directory, but I'm not sure if I put the template language in the correct place. 🙃 Let me know if it should go somewhere else!

To do

Confirm template language is in the correct place
Approval from @jsoriano
[outside this repo] Update the script for building integration docs to reformat code comments to prevent build failures cc @bmorelli25
After ☝️ is complete, merge this PR

elasticmachine · 2022-08-30T23:11:20Z

💚 Build Succeeded

the below badges are clickable and redirect to their specific view in the CI or DOCS

Expand to view the summary

Build stats

Start Time: 2022-09-12T11:08:42.955+0000
Duration: 30 min 3 sec

Test stats 🧪

Test	Results
Failed	0
Passed	829
Skipped	0
Total	829

🤖 GitHub comments

To re-run your PR in the CI, just comment with:

/test : Re-trigger the build.

elasticmachine · 2022-08-30T23:11:34Z

🌐 Coverage report

Name	Metrics % (`covered/total`)	Diff
Packages	100.0% (`34/34`)	💚
Files	66.929% (`85/127`)	👍
Classes	61.667% (`111/180`)	👍
Methods	48.834% (`356/729`)	👍
Lines	32.231% (`3225/10006`)	👍
Conditionals	100.0% (`0/0`)	💚

jsoriano

Nice, this is going to help a lot to have consistent readmes. Thanks!

jsoriano

Added a couple of suggestion I have just thought about.

jsoriano · 2022-09-05T07:14:27Z

internal/packages/archetype/package_docs_readme.go

+<!-- ### {Data stream name}
+
+The ` + "`{data stream name}`" + ` data stream provides events from {source} of the following types: {list types}. -->
+


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.

jsoriano · 2022-09-05T07:15:16Z

internal/packages/archetype/package_docs_readme.go

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


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

{{event "status"}}

colleenmcginnis · 2022-09-06T19:08:37Z

@jsoriano can you help with the failing checks or tag in someone else to help? Thanks!

jsoriano · 2022-09-07T16:00:53Z

@jsoriano can you help with the failing checks or tag in someone else to help? Thanks!

Oh, I missed this is already a template.

Try to "print" the function call:

{{"{{event \"status\"}}"}}

mrodm · 2022-09-07T16:34:23Z

internal/packages/archetype/package_docs_readme.go

+<!-- 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.


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):

Release a new version of elastic-package with the changes mentioned above.

Add the links definitions file in integrations, that is introduced here: Added new file for links definitions integrations#4156

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.

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.

colleenmcginnis · 2022-09-07T17:01:35Z

@jsoriano I'm confused about your last comment. Can you clarify what needs to be updated?

jsoriano

@colleenmcginnis sorry for the confusion, find here as suggestions what I meant.

jsoriano · 2022-09-07T17:17:05Z

internal/packages/archetype/package_docs_readme.go

+
+An example event for ` + "`{data stream name}`" + ` looks as following:
+
+{{event "{data stream}"}} -->


Suggested change

{{event "{data stream}"}} -->

{{"{{event \"{data stream}\"}}"}} -->

This seems complicated unless I'm missing something about how templates work. Would it work to just use this?

Suggested change

{{event "{data stream}"}} -->

\{\{event "{data stream}"\}\} -->

Or are you using the syntax above because the data stream name can be somehow automatically injected into the template?

jsoriano · 2022-09-07T17:17:32Z

internal/packages/archetype/package_docs_readme.go

+
+An example event for ` + "`{data stream name}`" + ` looks as following:
+
+{{event "{data stream}"}} -->


Suggested change

{{event "{data stream}"}} -->

{{"{{event \"{data stream}\"}}"}} -->

jsoriano · 2022-09-07T17:17:53Z

internal/packages/archetype/package_docs_readme.go

+
+<!-- #### Exported fields
+
+{{fields "{data stream}"}} -->`


Suggested change

{{fields "{data stream}"}} -->`

{{"{{fields \"{data stream}\"}}"}} -->`

jsoriano · 2022-09-08T08:57:43Z

Hey @colleenmcginnis, sorry for the back and forth, but after trying some things I think it'd be better to go back to the original version you sent before my suggestions in #954 (review).

The thing is that we have two ways of defining the readme in a package, one is using a static file, the other one is using a template that generates on build time the static file. The event and fields helpers only work when using the template, but elastic-package create package creates the static file, not the template, so my suggestion cannot work.

I think we need to refactor this code to be more coherent with our current recommendations. On most packages we are using the template and not the static file. In the meantime I think that we could merge your original changes.

Sorry again for the confusion!

This reverts commit b64e0e7.

jsoriano

Thanks!

add template language to packageDocsReadme

60b3c9a

colleenmcginnis requested a review from jsoriano August 30, 2022 22:43

colleenmcginnis self-assigned this Aug 30, 2022

jsoriano approved these changes Sep 5, 2022

View reviewed changes

jsoriano reviewed Sep 5, 2022

View reviewed changes

add helpers to generate example events and field tables

b64e0e7

colleenmcginnis marked this pull request as ready for review September 6, 2022 19:02

mrodm reviewed Sep 7, 2022

View reviewed changes

jsoriano reviewed Sep 7, 2022

View reviewed changes

Revert "add helpers to generate example events and field tables"

60a3eba

This reverts commit b64e0e7.

jsoriano approved these changes Sep 12, 2022

View reviewed changes

colleenmcginnis merged commit 58db47f into elastic:main Sep 12, 2022

colleenmcginnis deleted the issue-880 branch September 12, 2022 14:34

		<!-- ### {Data stream name}

		The ` + "`{data stream name}`" + ` data stream provides events from {source} of the following types: {list types}. -->


		An example event for ` + "`{data stream name}`" + ` looks as following:

		{{event "{data stream}"}} -->

	{{event "{data stream}"}} -->
	{{"{{event \"{data stream}\"}}"}} -->

	{{event "{data stream}"}} -->
	\{\{event "{data stream}"\}\} -->

	{{fields "{data stream}"}} -->`
	{{"{{fields \"{data stream}\"}}"}} -->`

Add docs template language to elastic-package create package #954

Add docs template language to elastic-package create package #954

Uh oh!

Conversation

colleenmcginnis commented Aug 30, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

To do

Uh oh!

elasticmachine commented Aug 30, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

💚 Build Succeeded

Build stats

Test stats 🧪

🤖 GitHub comments

Uh oh!

elasticmachine commented Aug 30, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🌐 Coverage report

Uh oh!

jsoriano left a comment

Choose a reason for hiding this comment

Uh oh!

jsoriano left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

colleenmcginnis commented Sep 6, 2022

Uh oh!

jsoriano commented Sep 7, 2022

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

colleenmcginnis commented Sep 7, 2022

Uh oh!

jsoriano left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jsoriano commented Sep 8, 2022

Uh oh!

jsoriano left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Add docs template language to `elastic-package create package` #954

Add docs template language to `elastic-package create package` #954

colleenmcginnis commented Aug 30, 2022 •

edited

Loading

elasticmachine commented Aug 30, 2022 •

edited

Loading

elasticmachine commented Aug 30, 2022 •

edited

Loading