Integrations developer guide

[bmorelli25]

Summary

The majority of this content was written by others. Some of the docs have been copy/pasted as-is (testing docs), while other docs have been changed considerably (build instructions). This PR won't be the final PR for the integrations developer guide, but I'd like to get this merged soon-ish so that others can start contributing as well.

Build locally

gh pr checkout 769
$GIT_HOME/docs/build_docs --doc $GIT_HOME/observability-docs/docs/en/integrations/index.asciidoc --resource $GIT_HOME/package-spec/versions --chunk 1 --open

Update preview

1. Update conf.yaml:

   package-spec:         https://github.com/elastic/package-spec.git

          - title:      Integrations Developer Guide
            prefix:     en/integrations-developer
            current:    master
            branches:   [ master ]
            live:       [ master ]
            index:      docs/en/integrations/index.asciidoc
            chunk:      1
            tags:       Integrations/Developer
            subject:    Integrations
            sources:
              -
                repo:   observability-docs
                path:   docs/en
              -
                repo:   docs
                path:   shared/versions/stack/{version}.asciidoc
              -
                repo:   docs
                path:   shared/attributes.asciidoc
              -
                repo:   package-spec
                path:   versions

2. Run the build_docs --all command:

$GIT_HOME/docs/build_docs --all \
    --target_repo git@github.com:elastic/built-docs.git \
    --target_branch integration-dev-guide \
    --push \
    --sub_dir observability-docs:master:$GIT_HOME/observability-docs

Related issues

Closes #583
Closes #984

Related PRs

Add to doc build: elastic/docs#2210

[apmmachine]

A documentation preview will be available soon:

• 📚 HTML diff
• 📘 Fleet User Guide
• 📙 Observability Guide

[bmorelli25]

Thank you for all the resources, @sorantis!

[mtojek]

Nice progress on the package docs!

Few points to consider:

elastic-package format - what is it, when to use it, which files will be formatted

elastic-package check - ultimate check before pushing it to the repository. If the "check" is happy, we know that the code is built correctly, formatted properly and it's aligned with the spec (linting passed).

You could also provide some guidance for designing forms in Kibana (UI and UX), cover recommendation for names, labels, descriptions. I tried to put them in: https://github.com/elastic/integrations/blob/master/docs/tips_for_building_integrations.md#manifest-files-1

[mtojek]

Hi @bmorelli25 ,

I see that you copied content from elastic-package READMEs. Do you have a plan for updating it in the future? We used to modify README files from time to time, so these .asciidocs will become outdated really soon.

[bmorelli25]

Hi @mtojek! Sorry for the delay. A long PTO break and other projects have gotten in the way. Returning to this now.

Do you have a plan for updating it in the future?

Concrete plan, no. Eventually, we'd like the only documentation for these commands to exist in the Integrations developer guide. We discussed documenting these commands in a yaml file in the elastic-package repository with a script that can be used to extract and build to mdx. But that's still a pipe dream at this point.

[mtojek]

Same concern about service deployers. Does it mean that we have to apply changes in both places to keep them up-to-date?

[bmorelli25]

It's a good point. I'll bring this up in our weekly tomorrow. There might just be too many manual copy/paste steps required to move forward with this PR at this point.

[bmorelli25]

In the end, I may just have to update things manually for a release or two until we figure out the automation side of things

[mtojek]

It's also a good candidate for an example. Keep in mind this is a feature for advanced users who want to modify the default setup.

[bmorelli25]

I'd probably need help on an example here. I'm not sure I understand what the command is used for.

[EamonnTP]

@bmorelli25 Looks great so far. It's quite lengthy, so I only managed to review a few of the topics - just minor suggestions. I'll review the rest of the topics tomorrow.

[EamonnTP]

Second round! Just minor suggestions. Otherwise, it looks great!

[bmorelli25]

This is ready for final review. I'll merge on Tuesday. Thanks to everyone for their help.