[DOCS] Adds conceptual content to API docs#202305
Merged
natasha-moore-elastic merged 17 commits intoelastic:mainfrom Dec 12, 2024
natasha-moore-elastic:issue-49-apidocs
Merged
[DOCS] Adds conceptual content to API docs#202305natasha-moore-elastic merged 17 commits intoelastic:mainfrom natasha-moore-elastic:issue-49-apidocs
natasha-moore-elastic merged 17 commits intoelastic:mainfrom
natasha-moore-elastic:issue-49-apidocs
Conversation
natasha-moore-elastic
added
Team:Docs
release_note:skip
7 tasks
Contributor
|
Pinging @elastic/kibana-docs (Team:Docs) |
Contributor
|
Pinging @elastic/security-detections-response (Team:Detections and Resp) |
Contributor
|
Pinging @elastic/security-detection-rule-management (Team:Detection Rule Management) |
Contributor
|
Pinging @elastic/security-detection-engine (Team:Detection Engine) |
maximpn
reviewed
Dec 10, 2024
Contributor
maximpn
left a comment
maximpn
left a comment
There was a problem hiding this comment.
@natasha-moore-elastic Thanks for addressing my comments 🙏
It looks cleaner though I'm a bit concerned with maintainability and have some ideas regarding "prototype" files
- Term "prototype" isn't well known and may confuse readers.
oas_docsfolder useskibana.info.yaml. Maybe we could stick to the same naming for consistency. For example renameexceptions_prototype_ess.yamltoexceptions_ess.info.yaml. - "Prototype" files aren't documentation on its own. It doesn't look like such files should be placed in
docsfolder. I'd prefer location next to the script files to make it much more prominent that these new YAML files belong to scripts. It's ok to put them in a subfolder.
WDYT?
Contributor
Author
Thanks @maximpn – I as mentioned above, I wasn't sure about the naming and location for the new files, so this is useful feedback. 🙏
Just to clarify, should the files be directly inside the |
Contributor
@natasha-moore-elastic It looks like having a subfolder will be consistent across different cases. Some name like |
maximpn
approved these changes
Dec 12, 2024
Contributor
maximpn
left a comment
maximpn
left a comment
There was a problem hiding this comment.
@natasha-moore-elastic Thanks for addressing my comments 👍
Bundling scripts and Rule Management changes LGTM
Contributor
There was a problem hiding this comment.
nit: Do you think the folder name detections_bundle_info would be better?
Contributor
Author
There was a problem hiding this comment.
For that folder I followed the name of the script, which is bundle_detections.js, so I'm inclined to leave it as is if it doesn't make a huge difference.
vitaliidm
approved these changes
Dec 12, 2024
Contributor
💛 Build succeeded, but was flaky
Failed CI StepsTest Failures
Metrics [docs]
History
|
Contributor
|
Starting backport for target branches: 8.16, 8.17 https://github.com/elastic/kibana/actions/runs/12301048666 |
Contributor
💔 All backports failed
Manual backportTo create the backport manually run: Questions ?Please refer to the Backport tool documentation |
This was referenced Dec 12, 2024
Contributor
Author
💔 Some backports could not be created
Note: Successful backport PRs will be merged automatically after passing CI. Manual backportTo create the backport manually run: Questions ?Please refer to the Backport tool documentation |
Contributor
Author
💚 All backports created successfully
Note: Successful backport PRs will be merged automatically after passing CI. Questions ?Please refer to the Backport tool documentation |
natasha-moore-elastic
added a commit
that referenced
this pull request
Dec 13, 2024
# Backport This will backport the following commits from `main` to `8.x`: - [[DOCS] Adds conceptual content to API docs (#202305)](#202305) <!--- Backport version: 8.9.8 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) <!--BACKPORT [{"author":{"name":"natasha-moore-elastic","email":"137783811+natasha-moore-elastic@users.noreply.github.com"},"sourceCommit":{"committedDate":"2024-12-12T16:53:29Z","message":"[DOCS] Adds conceptual content to API docs (#202305)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/security-docs-internal/issues/49.\r\n\r\nIn order to retire asciidoc API docs, we first need to move over any\r\nrelevant content from those docs to the API reference site. This PR adds\r\nthe relevant conceptual information from:\r\n\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/exceptions-api-overview.html\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/lists-api-overview.html\r\n- https://www.elastic.co/guide/en/security/master/rule-api-overview.html\r\n\r\n### Previews:\r\nBump previews expire after 30min, so I'm providing screenshots below:\r\n\r\nDetections preview:\r\n\r\n\r\n\r\nExceptions preview:\r\n\r\n\r\n\r\nLists preview:\r\n\r\n\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"cebcf01d35b84308e1ca9eabed694864a9e39ed9","branchLabelMapping":{"^v9.0.0$":"main","^v8.18.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Docs","release_note:skip","v9.0.0","Feature:Detection Rules","docs","Team:Detections and Resp","Feature:Rule Exceptions","APIDocs","Team:Detection Rule Management","Team:Detection Engine","backport:version","v8.17.0","v8.16.2"],"number":202305,"url":"https://github.com/elastic/kibana/pull/202305","mergeCommit":{"message":"[DOCS] Adds conceptual content to API docs (#202305)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/security-docs-internal/issues/49.\r\n\r\nIn order to retire asciidoc API docs, we first need to move over any\r\nrelevant content from those docs to the API reference site. This PR adds\r\nthe relevant conceptual information from:\r\n\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/exceptions-api-overview.html\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/lists-api-overview.html\r\n- https://www.elastic.co/guide/en/security/master/rule-api-overview.html\r\n\r\n### Previews:\r\nBump previews expire after 30min, so I'm providing screenshots below:\r\n\r\nDetections preview:\r\n\r\n\r\n\r\nExceptions preview:\r\n\r\n\r\n\r\nLists preview:\r\n\r\n\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"cebcf01d35b84308e1ca9eabed694864a9e39ed9"}},"sourceBranch":"main","suggestedTargetBranches":["8.17","8.16"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/202305","number":202305,"mergeCommit":{"message":"[DOCS] Adds conceptual content to API docs (#202305)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/security-docs-internal/issues/49.\r\n\r\nIn order to retire asciidoc API docs, we first need to move over any\r\nrelevant content from those docs to the API reference site. This PR adds\r\nthe relevant conceptual information from:\r\n\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/exceptions-api-overview.html\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/lists-api-overview.html\r\n- https://www.elastic.co/guide/en/security/master/rule-api-overview.html\r\n\r\n### Previews:\r\nBump previews expire after 30min, so I'm providing screenshots below:\r\n\r\nDetections preview:\r\n\r\n\r\n\r\nExceptions preview:\r\n\r\n\r\n\r\nLists preview:\r\n\r\n\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"cebcf01d35b84308e1ca9eabed694864a9e39ed9"}},{"branch":"8.17","label":"v8.17.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.16","label":"v8.16.2","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"}]}] BACKPORT-->
natasha-moore-elastic
added a commit
that referenced
this pull request
Dec 13, 2024
# Backport This will backport the following commits from `main` to `8.17`: - [[DOCS] Adds conceptual content to API docs (#202305)](#202305) <!--- Backport version: 8.9.8 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) <!--BACKPORT [{"author":{"name":"natasha-moore-elastic","email":"137783811+natasha-moore-elastic@users.noreply.github.com"},"sourceCommit":{"committedDate":"2024-12-12T16:53:29Z","message":"[DOCS] Adds conceptual content to API docs (#202305)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/security-docs-internal/issues/49.\r\n\r\nIn order to retire asciidoc API docs, we first need to move over any\r\nrelevant content from those docs to the API reference site. This PR adds\r\nthe relevant conceptual information from:\r\n\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/exceptions-api-overview.html\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/lists-api-overview.html\r\n- https://www.elastic.co/guide/en/security/master/rule-api-overview.html\r\n\r\n### Previews:\r\nBump previews expire after 30min, so I'm providing screenshots below:\r\n\r\nDetections preview:\r\n\r\n\r\n\r\nExceptions preview:\r\n\r\n\r\n\r\nLists preview:\r\n\r\n\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"cebcf01d35b84308e1ca9eabed694864a9e39ed9","branchLabelMapping":{"^v9.0.0$":"main","^v8.18.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Docs","release_note:skip","v9.0.0","Feature:Detection Rules","docs","Team:Detections and Resp","Feature:Rule Exceptions","APIDocs","Team:Detection Rule Management","Team:Detection Engine","backport:version","v8.17.0","v8.16.2"],"number":202305,"url":"https://github.com/elastic/kibana/pull/202305","mergeCommit":{"message":"[DOCS] Adds conceptual content to API docs (#202305)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/security-docs-internal/issues/49.\r\n\r\nIn order to retire asciidoc API docs, we first need to move over any\r\nrelevant content from those docs to the API reference site. This PR adds\r\nthe relevant conceptual information from:\r\n\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/exceptions-api-overview.html\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/lists-api-overview.html\r\n- https://www.elastic.co/guide/en/security/master/rule-api-overview.html\r\n\r\n### Previews:\r\nBump previews expire after 30min, so I'm providing screenshots below:\r\n\r\nDetections preview:\r\n\r\n\r\n\r\nExceptions preview:\r\n\r\n\r\n\r\nLists preview:\r\n\r\n\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"cebcf01d35b84308e1ca9eabed694864a9e39ed9"}},"sourceBranch":"main","suggestedTargetBranches":["8.17"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/202305","number":202305,"mergeCommit":{"message":"[DOCS] Adds conceptual content to API docs (#202305)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/security-docs-internal/issues/49.\r\n\r\nIn order to retire asciidoc API docs, we first need to move over any\r\nrelevant content from those docs to the API reference site. This PR adds\r\nthe relevant conceptual information from:\r\n\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/exceptions-api-overview.html\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/lists-api-overview.html\r\n- https://www.elastic.co/guide/en/security/master/rule-api-overview.html\r\n\r\n### Previews:\r\nBump previews expire after 30min, so I'm providing screenshots below:\r\n\r\nDetections preview:\r\n\r\n\r\n\r\nExceptions preview:\r\n\r\n\r\n\r\nLists preview:\r\n\r\n\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"cebcf01d35b84308e1ca9eabed694864a9e39ed9"}},{"branch":"8.17","label":"v8.17.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.16","label":"v8.16.2","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"url":"https://github.com/elastic/kibana/pull/204108","number":204108,"state":"OPEN"},{"url":"https://github.com/elastic/kibana/pull/204106","number":204106,"branch":"8.x","state":"OPEN"}]}] BACKPORT-->
natasha-moore-elastic
added a commit
that referenced
this pull request
Dec 13, 2024
# Backport This will backport the following commits from `main` to `8.16`: - [[DOCS] Adds conceptual content to API docs (#202305)](#202305) <!--- Backport version: 8.9.8 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) <!--BACKPORT [{"author":{"name":"natasha-moore-elastic","email":"137783811+natasha-moore-elastic@users.noreply.github.com"},"sourceCommit":{"committedDate":"2024-12-12T16:53:29Z","message":"[DOCS] Adds conceptual content to API docs (#202305)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/security-docs-internal/issues/49.\r\n\r\nIn order to retire asciidoc API docs, we first need to move over any\r\nrelevant content from those docs to the API reference site. This PR adds\r\nthe relevant conceptual information from:\r\n\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/exceptions-api-overview.html\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/lists-api-overview.html\r\n- https://www.elastic.co/guide/en/security/master/rule-api-overview.html\r\n\r\n### Previews:\r\nBump previews expire after 30min, so I'm providing screenshots below:\r\n\r\nDetections preview:\r\n\r\n\r\n\r\nExceptions preview:\r\n\r\n\r\n\r\nLists preview:\r\n\r\n\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"cebcf01d35b84308e1ca9eabed694864a9e39ed9","branchLabelMapping":{"^v9.0.0$":"main","^v8.18.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Docs","release_note:skip","v9.0.0","Feature:Detection Rules","docs","Team:Detections and Resp","Feature:Rule Exceptions","APIDocs","Team:Detection Rule Management","Team:Detection Engine","backport:version","v8.17.0","v8.16.2"],"number":202305,"url":"https://github.com/elastic/kibana/pull/202305","mergeCommit":{"message":"[DOCS] Adds conceptual content to API docs (#202305)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/security-docs-internal/issues/49.\r\n\r\nIn order to retire asciidoc API docs, we first need to move over any\r\nrelevant content from those docs to the API reference site. This PR adds\r\nthe relevant conceptual information from:\r\n\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/exceptions-api-overview.html\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/lists-api-overview.html\r\n- https://www.elastic.co/guide/en/security/master/rule-api-overview.html\r\n\r\n### Previews:\r\nBump previews expire after 30min, so I'm providing screenshots below:\r\n\r\nDetections preview:\r\n\r\n\r\n\r\nExceptions preview:\r\n\r\n\r\n\r\nLists preview:\r\n\r\n\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"cebcf01d35b84308e1ca9eabed694864a9e39ed9"}},"sourceBranch":"main","suggestedTargetBranches":["8.17","8.16"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/202305","number":202305,"mergeCommit":{"message":"[DOCS] Adds conceptual content to API docs (#202305)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/security-docs-internal/issues/49.\r\n\r\nIn order to retire asciidoc API docs, we first need to move over any\r\nrelevant content from those docs to the API reference site. This PR adds\r\nthe relevant conceptual information from:\r\n\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/exceptions-api-overview.html\r\n-\r\nhttps://www.elastic.co/guide/en/security/master/lists-api-overview.html\r\n- https://www.elastic.co/guide/en/security/master/rule-api-overview.html\r\n\r\n### Previews:\r\nBump previews expire after 30min, so I'm providing screenshots below:\r\n\r\nDetections preview:\r\n\r\n\r\n\r\nExceptions preview:\r\n\r\n\r\n\r\nLists preview:\r\n\r\n\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"cebcf01d35b84308e1ca9eabed694864a9e39ed9"}},{"branch":"8.17","label":"v8.17.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.16","label":"v8.16.2","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"}]}] BACKPORT-->
Contributor
|
@natasha-moore-elastic Reviewed post-merge, but LGTM 👍 Thank you for making this improvement! Wondering what's the plan for the rest of the pages outlined in https://github.com/elastic/security-docs-internal/issues/49? |
Contributor
Author
Thanks for having a look @banderror! We reviewed all asciidoc pages that had conceptual information (mentioned in https://github.com/elastic/security-docs-internal/issues/49) to see what needs to be moved over to the API reference. The content that wasn't moved over in this PR was either outdated or already exists elsewhere in the API reference/UI docs, so we decided against moving/duplicating that content. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
7 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Resolves https://github.com/elastic/security-docs-internal/issues/49.
In order to retire asciidoc API docs, we first need to move over any relevant content from those docs to the API reference site. This PR adds the relevant conceptual information from:
Previews:
Bump previews expire after 30min, so I'm providing screenshots below:
Detections preview:
Exceptions preview:
Lists preview:
