docs: split up steps into separate reference pages #3275
Conversation
Signed-off-by: Hidde Beydals <[email protected]>
✅ Deploy Preview for docs-kargo-io ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Signed-off-by: Hidde Beydals <[email protected]>
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## newdocs #3275 +/- ##
==========================================
Coverage ? 52.05%
==========================================
Files ? 295
Lines ? 26695
Branches ? 0
==========================================
Hits ? 13895
Misses ? 12041
Partials ? 759 ☔ View full report in Codecov by Sentry. |
Signed-off-by: Kent Rancourt <[email protected]>
|
I updated the relative URLs to exclude numbers. In some older configuration (it might have been with Docusaurus 2), we seemed to need them, but we no longer do. |
| | `checkout[].commit` | `string` | N | A specific commit to check out. Mutually exclusive with `branch`, `tag`, and `fromFreight=true`. If none of these is specified, the default branch will be checked out. | | ||
| | `checkout[].tag` | `string` | N | A tag to check out. Mutually exclusive with `branch`, `commit`, and `fromFreight=true`. If none of these is specified, the default branch will be checked out. | | ||
| | `checkout[].fromFreight` | `boolean` | N | Whether a commit to check out should be obtained from the Freight being promoted. A value of `true` is mutually exclusive with `branch`, `commit`, and `tag`. If none of these is specified, the default branch will be checked out. Default is `false`, but is often set to `true`. <br/><br/>__Deprecated: Use `commit` with an expression instead. Will be removed in v1.3.0.__ | | ||
| | `checkout[].fromOrigin` | `object` | N | See [specifying origins](#specifying-origins). <br/><br/>__Deprecated: Use `commit` with an expression instead. Will be removed in v1.3.0.__ | |
There was a problem hiding this comment.
All #specifying-origins are broken... but (I've just realized) they are in the existing docs as well. It seems that section was prematurely removed in the v1.1 docs. Need to go back to v1.0 to find it: https://release-1-0.docs.kargo.io/references/promotion-steps#specifying-origins
We could fix this or especially since it is only deprecated fields that reference this, we could leave it be or remove these links. I don't have any strong opinion.
There was a problem hiding this comment.
This otherwise LGTM, so I'm approving and I am content with however you decide to deal with this (or not).
|
@krancour not sure about the relative URLs being an improvement, for a couple of reasons:
If the primary concern is, "whenever I reorder files, I do not want to update references", I suggest we follow the actual advice from Docusaurus (see their warning here) and move the ordering to the front matter (as documented here). |
Replacement for #3272 targeting
newdocs.This splits the single page with step documentation into multiple pages, accompanied by an auto-generated index.
As a follow-up, the previous "Promotion Step Reference" document will be turned into a broader "Promotion Template Reference" document and paired with a dedicated "Promotion Task Reference" page.
All pages have the same structure and headings, e.g. "Configuration", "Output" (where applicable), and "Examples". This is to ease navigation for the user.