Use subpages for third party deps and API #8757

barkbay · 2025-07-18T09:01:01Z

This PR introduces some changes to generate third-party deps and API reference versioned pages.

Do not merge before 3.1

prodsecmachine · 2025-07-18T09:01:15Z

🎉 Snyk checks have passed. No issues have been found so far.

✅ security/snyk check is complete. No issues have been found. (View Details)

✅ license/snyk check is complete. No issues have been found. (View Details)

github-actions · 2025-07-18T09:13:06Z

🔍 Preview links for changed docs

barkbay · 2025-07-18T09:47:13Z

Landing page does not look great with

toc:
  - file: index.md
  - file: api-docs.md
  - folder: third-party-dependencies
  - file: eck-configuration-flags.md
  - file: upgrade-predicates.md

⬇️

I don't understand why previous is "third-party deps" while I would expect it to be the next since it is a child?

eedugon · 2025-07-18T10:24:32Z

I don't understand why previous is "third-party deps" while I would expect it to be the next since it is a child?

I think our previous views have some limitations, and maybe that's one of them.

Landing page does not look great with

What part you don't like and what would you like to improve? Maybe I can help you with that!

This reverts commit d808d2e.

barkbay · 2025-07-21T08:21:58Z

hack/licence-detector/generate-notice.sh

        cd "$PROJECT_DIR"
        go mod download
        go list -m -json all | "${TEMP_DIR}"/go-licence-detector \
            -depsTemplate="${SCRIPT_DIR}"/templates/dependencies.md.tmpl \
-            -depsOut="${PROJECT_DIR}"/docs/reference/third-party-dependencies.md \
+            -template-value=eckVersion="${version}" \


This relies on elastic/go-licence-detector#29

barkbay · 2025-07-21T08:44:01Z

Preview with the new template:

barkbay · 2025-07-22T08:15:39Z

This PR is ready for review 🎉 , the preview is available here: https://docs-v3-preview.elastic.dev/elastic/cloud-on-k8s/pull/8757/reference

barkbay · 2025-07-22T08:18:29Z

docs/reference/api-docs.md

@@ -1,2073 +1,13 @@
 ---
 mapped_pages:
  - https://www.elastic.co/guide/en/cloud-on-k8s/current/k8s-api-reference.html
-navigation_title: API Reference
+navigation_title: API Reference (moved)


I had to preserve that page because it is referenced in the docs-content repo, doc generation fails if I remove it. I believe we can fix that in a follow up PR once this one is merged.

pebrc

LGTM! Nice work! As we release more versions of ECK we might have to revisit this strategy especially if there is an empty diff between versions it might make sense to think about grouping multiple versions in one document or something along those lines. But for now I am super happy we have a path forward.

barkbay · 2025-07-22T09:17:32Z

docs/reference/api-reference/3_0_0.md

@@ -4,7 +4,7 @@ mapped_pages:
 navigation_title: API Reference for 3.0.0
 applies_to:
  deployment:
-    eck: ga 3.0.0
+    eck: ga 3.0.0, ga 3.1.0


@pebrc I tested what we discussed out of band, here is the result:

Very nice! This opens then indeed the door to collapse documentation for mulitple versions into one page.

This reverts commit 29d20d8.

eedugon · 2025-07-22T13:40:59Z

@barkbay : should we remove the API reference and 3PP references docs identified as from the main branch? What's the value of them when we'll have the 3.0.0 and 3.0.1 versions published?

shainaraskas · 2025-07-22T21:14:59Z

docs/reference/api-reference/3_1_0.md

I just quickly diffed the two api references and I'm not seeing any substantive differences (one line about fleet advanced config). do we need to generate these as separate pages right now? do you expect substantive development to come to this area soon?

I also wonder how the versioning approach for the API packages (e.g. v1, v1beta1, v1alpha1) interact with the versioning for ECK itself. it feels possibly like the API reference needs to follow its own versioning scheme based on these hints.

if that's the case, maybe we could state which api versions are compatible with which stack versions as an alternative

one line about fleet advanced config

This is something new in ECK 3.1.0, which was not supported in 3.0.0. So I think I would keep 2 separate files.

I also wonder how the versioning approach for the API packages (e.g. v1, v1beta1, v1alpha1) interact with the versioning for ECK itself.

Each K8S API version stage can be used to represent a different maturity and stability level. When a new version is introduced it also requires a change in the operator. They are not related to stack versions.

This is something new in ECK 3.1.0, which was not supported in 3.0.0. So I think I would keep 2 separate files.

this is the substance of the change:

the change does not seem to a change to the API functionality (unless this is missing a related value for the new config model). Given this, I'd rather rely on the applicability information in the core docs than generate a whole new API reference for a clarifying sentence.

Each K8S API version stage can be used to represent a different maturity and stability level. When a new version is introduced it also requires a change in the operator. They are not related to stack versions.

it sounds like the version stage doesn't actually guarantee specific behavior independently of the eck version, so it still makes sense to use the ECK version as the primary versioning model 👍

shainaraskas · 2025-07-22T21:22:53Z

should we remove the API reference and 3PP references docs identified as from the main branch? What's the value of them when we'll have the 3.0.0 and 3.0.1 versions published?

if we still want to generate them for internal/dev use, we could consider making them hidden files so they can be visited but not consumed by readers who might be confused by them

shainaraskas

overall, this looks really great, and thank you for taking on the effort of refactoring the generation so quickly. my key piece of feedback is that we should think about the long-term vision for the API reference before we build a bunch of pages we need to maintain long term.

shainaraskas · 2025-07-22T21:18:07Z

docs/reference/third-party-dependencies/index.md

+
+# Third-party dependencies [k8s-reference-dependencies]
+
+This section contains reference information about third-party dependencies used by {{eck}}.


this file should ideally link to the children in the section

shainaraskas · 2025-07-22T21:19:13Z

docs/reference/toc.yml

@@ -1,6 +1,7 @@
 toc:
  - file: index.md
  - file: api-docs.md
-  - file: third-party-dependencies.md
+  - folder: api-reference
+  - folder: third-party-dependencies


I think that because we're using this folder model rather than a file/children model, these are being listed in a weird order. ideally, we'd list these dependency files from newest to oldest:

yes 😕 , I think it would be a bit more complex to automate the generation of these files with the file/children model.

docs/reference/third-party-dependencies/3_1_0.md

barkbay · 2025-07-23T06:07:47Z

What's the value of them when we'll have the 3.0.0 and 3.1.0 versions published?

IIRC we have to document third-party dependencies for compliance purposes, not sure if this includes the ones currently referenced by the project in its main branch though. I think it is also helpful to ensure that we can always generate these files, without waiting for a new release branch to be created. So maybe we can hide them as suggested, @pebrc do you have an opinion?

barkbay · 2025-07-23T06:47:01Z

Preview of the new navigation titles:

pebrc · 2025-07-23T07:03:57Z

What's the value of them when we'll have the 3.0.0 and 3.1.0 versions published?

IIRC we have to document third-party dependencies for compliance purposes, not sure if this includes the ones currently referenced by the project in its main branch though. I think it is also helpful to ensure that we can always generate these files, without waiting for a new release branch to be created. So maybe we can hide them as suggested, @pebrc do you have an opinion?

Hiding the file for the main branch sounds like a good option to me. And I agree we should keep generating the file for main to make sure your our generation tooling is functional.

barkbay · 2025-07-23T08:05:31Z

if we still want to generate them for internal/dev use, we could consider making them hidden files so they can be visited but not consumed by readers who might be confused by them

Are hidden files compatible with the fact that we want to avoid the file/children model?

shainaraskas · 2025-07-23T16:45:56Z

Are hidden files compatible with the fact that we want to avoid the file/children model?

unfortunately, I don't think so. if we needed to, we could ship this and revisit a more granular toc separately.

barkbay added >docs Documentation v3.1.0 labels Jul 18, 2025

github-actions bot deployed to docs-preview July 18, 2025 09:01 View deployment

barkbay force-pushed the docs/subpages branch from b53f643 to dba1193 Compare July 18, 2025 09:03

github-actions bot deployed to docs-preview July 18, 2025 09:04 View deployment

barkbay force-pushed the docs/subpages branch from dba1193 to df1372e Compare July 18, 2025 09:05

github-actions bot deployed to docs-preview July 18, 2025 09:06 View deployment

barkbay force-pushed the docs/subpages branch from df1372e to 253cb8c Compare July 18, 2025 09:12

github-actions bot deployed to docs-preview July 18, 2025 09:12 View deployment

barkbay force-pushed the docs/subpages branch from 253cb8c to 76f623c Compare July 18, 2025 09:36

github-actions bot deployed to docs-preview July 18, 2025 09:37 View deployment

Test

91d8930

barkbay force-pushed the docs/subpages branch from 76f623c to 91d8930 Compare July 18, 2025 09:41

github-actions bot deployed to docs-preview July 18, 2025 09:42 View deployment

Explicitly set children

d808d2e

github-actions bot deployed to docs-preview July 18, 2025 11:23 View deployment

barkbay added 3 commits July 18, 2025 13:31

Revert "Explicitly set children", it does not improve things

41d6b7f

This reverts commit d808d2e.

Update hack/licence-detector/generate-notice.sh

3df2c97

rename

d95315c

barkbay commented Jul 21, 2025

View reviewed changes

barkbay added 2 commits July 21, 2025 10:24

Update template

49318d8

Update applies_to

8ec671a

barkbay added 3 commits July 21, 2025 10:46

Update comment

9ba5d46

Extract common functions

f126059

Use function to get ECK version

2908f74

barkbay requested review from pebrc, naemono, rhr323, eedugon, shainaraskas and kvalliyurnatt July 22, 2025 08:14

barkbay commented Jul 22, 2025

View reviewed changes

pebrc approved these changes Jul 22, 2025

View reviewed changes

test

29d20d8

barkbay commented Jul 22, 2025

View reviewed changes

Revert "test"

84b4ccf

This reverts commit 29d20d8.

shainaraskas reviewed Jul 22, 2025

View reviewed changes

Simplify navigation titles

60f92af

Test hidden files

ea399bd

Test hidden files (again)

e314bb8

barkbay added 4 commits July 24, 2025 10:50

Remove hidden files as it does not work in our case

77809c8

Merge remote-tracking branch 'origin/main' into docs/subpages

ead5703

make generate

63cafd6

Merge branch 'main' into docs/subpages

b512ca0

barkbay merged commit 6b3487d into elastic:main Jul 30, 2025
9 checks passed

barkbay deleted the docs/subpages branch July 30, 2025 07:53


		# Third-party dependencies [k8s-reference-dependencies]

		This section contains reference information about third-party dependencies used by {{eck}}.

Use subpages for third party deps and API #8757

Use subpages for third party deps and API #8757

Uh oh!

Conversation

barkbay commented Jul 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

prodsecmachine commented Jul 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎉 Snyk checks have passed. No issues have been found so far.

Uh oh!

github-actions bot commented Jul 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

barkbay commented Jul 18, 2025

Uh oh!

eedugon commented Jul 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

barkbay commented Jul 21, 2025

Uh oh!

barkbay commented Jul 22, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pebrc 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!

eedugon commented Jul 22, 2025

Uh oh!

shainaraskas Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

shainaraskas commented Jul 22, 2025

Uh oh!

shainaraskas 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!

Uh oh!

barkbay commented Jul 23, 2025

Uh oh!

barkbay commented Jul 23, 2025

Uh oh!

pebrc commented Jul 23, 2025

Uh oh!

barkbay commented Jul 23, 2025

Uh oh!

shainaraskas commented Jul 23, 2025

Uh oh!

Uh oh!

Uh oh!

barkbay commented Jul 18, 2025 •

edited

Loading

prodsecmachine commented Jul 18, 2025 •

edited

Loading

github-actions bot commented Jul 18, 2025 •

edited

Loading

eedugon commented Jul 18, 2025 •

edited

Loading

shainaraskas Jul 22, 2025 •

edited

Loading