From 5d765500614fb6ca3d50c11b114c51024c430a0b Mon Sep 17 00:00:00 2001 From: Giovanni Liva Date: Thu, 30 Nov 2023 10:00:31 +0100 Subject: [PATCH] fix links and nav Signed-off-by: Giovanni Liva --- .../docs/components/certificate-operator.md | 4 +- docs-new/docs/components/metrics-operator.md | 10 ++--- docs-new/docs/components/scheduling.md | 4 +- .../docs/contrib-guidelines-docs.md | 6 +-- .../contribute/docs/source-file-structure.md | 31 ++++++++------- docs-new/docs/contribute/docs/word-list.md | 4 +- .../general/contrib-guidelines-gen.md | 2 +- .../contribute/general/git/branch-create.md | 6 +-- .../docs/contribute/general/git/fork-clone.md | 2 +- .../docs/contribute/general/git/pr-create.md | 4 +- mkdocs.yml | 38 +++++++++---------- 11 files changed, 57 insertions(+), 54 deletions(-) diff --git a/docs-new/docs/components/certificate-operator.md b/docs-new/docs/components/certificate-operator.md index cd4b7806ac..ff846acdcc 100644 --- a/docs-new/docs/components/certificate-operator.md +++ b/docs-new/docs/components/certificate-operator.md @@ -5,7 +5,7 @@ The Keptn Cert Manager automatically configures TLS certificates to [secure communication with the Kubernetes API](https://kubernetes.io/docs/concepts/security/controlling-access/#transport-security). You can instead -[use cert-manager.io](../../installation/configuration/cert-manager.md) +[use cert-manager.io](../installation/configuration/cert-manager.md) for this purpose. Keptn includes a Mutating Webhook @@ -32,7 +32,7 @@ It is included to simplify installation for new users and because it is much smaller than most standard certificate managers. However, Keptn is compatible with most certificate managers and can be configured to use another certificate manager if you prefer. -See [Use Keptn with cert-manager.io](../../installation/configuration/cert-manager.md) +See [Use Keptn with cert-manager.io](../installation/configuration/cert-manager.md) for instructions. ## Invalid certificate errors diff --git a/docs-new/docs/components/metrics-operator.md b/docs-new/docs/components/metrics-operator.md index d9b919067f..b10fd720ee 100644 --- a/docs-new/docs/components/metrics-operator.md +++ b/docs-new/docs/components/metrics-operator.md @@ -22,7 +22,7 @@ so they are compatible with the Kubernetes (HPA), which enables the horizontal scaling of workloads based on metrics collected from multiple observability platforms. See -[Using the HorizontalPodAutoscaler](../../use-cases/hpa.md) +[Using the HorizontalPodAutoscaler](../use-cases/hpa.md) for instructions. The Metrics Operator consists of the following components: @@ -49,18 +49,18 @@ which can be used to gain insight into the behavior and performance of applications running on a Kubernetes cluster. The **Metrics controller** fetches metrics from an SLI provider. -The controller reconciles a [`KeptnMetric`](../../reference/crd-reference/metric.md) +The controller reconciles a [`KeptnMetric`](../reference/crd-reference/metric.md) resource and updates its status with the metric value provided by the selected metric provider. Each `KeptnMetric` is identified by `name` and is associated with an instance of an observability platform that is defined in a -[KeptnMetricsProvider](../../reference/crd-reference/metricsprovider.md) +[KeptnMetricsProvider](../reference/crd-reference/metricsprovider.md) resource. The steps in which the controller fetches metrics are given below: -1. When a [`KeptnMetric`](../../reference/crd-reference/metric.md) +1. When a [`KeptnMetric`](../reference/crd-reference/metric.md) resource is found or modified, the controller checks whether the metric has been updated within the interval that is defined in the `spec.fetchintervalseconds` field. @@ -80,7 +80,7 @@ The steps in which the controller fetches metrics are given below: in the `status` field of the `KeptnMetric` object. * If the evaluation fails, the error and reason is written to the - [KeptnMetricStatus](../../reference/api-reference/metrics/v1beta1/index.md#keptnmetricstatus) + [KeptnMetricStatus](../reference/api-reference/metrics/v1beta1/index.md#keptnmetricstatus) resource. The error is described in both human-readable language and as raw data to help identify the source of the problem diff --git a/docs-new/docs/components/scheduling.md b/docs-new/docs/components/scheduling.md index 294fce3414..48ca50f143 100644 --- a/docs-new/docs/components/scheduling.md +++ b/docs-new/docs/components/scheduling.md @@ -26,7 +26,7 @@ to gate Pods until the required deployment checks pass. When a workload is applied to a Kubernetes cluster, the Mutating Webhook checks each Pod for annotations. If -[Keptn specific annotations](../../guides/integrate.md#basic-annotations) +[Keptn specific annotations](../guides/integrate.md#basic-annotations) are present, the Webhook adds a scheduling gate to the Pod called `keptn-prechecks-gate`. This spec tells the Kubernetes scheduling framework @@ -67,7 +67,7 @@ a [Permit plugin](https://kubernetes.io/docs/concepts/scheduling-eviction/schedu ### How does the Keptn Scheduler works Firstly the Mutating Webhook checks for annotations on Pods to see if it is annotated with -[Keptn specific annotations](../../guides/integrate.md#basic-annotations). +[Keptn specific annotations](../guides/integrate.md#basic-annotations). If the annotations are present, the Webhook assigns the **Keptn Scheduler** to the Pod. This ensures that the Keptn Scheduler only gets Pods that have been annotated for it. A Pod `test-pod` modified by the Mutating Webhook looks as follows: diff --git a/docs-new/docs/contribute/docs/contrib-guidelines-docs.md b/docs-new/docs/contribute/docs/contrib-guidelines-docs.md index 3391288cd2..18ad3e4595 100644 --- a/docs-new/docs/contribute/docs/contrib-guidelines-docs.md +++ b/docs-new/docs/contribute/docs/contrib-guidelines-docs.md @@ -1,6 +1,6 @@ # Contribution guidelines for documentation -The [Contribution Guidelines](../../general/contrib-guidelines-gen/index.md) page +The [Contribution Guidelines](../general/contrib-guidelines-gen.md) page contains guidelines that are relevant for both documentation and software contributions. This page lists additional guidelines @@ -86,7 +86,7 @@ that are relevant only to documentation * Always build the documentation locally to check the formatting and verify that all links are working properly. - See [Build Documentation Locally](../local-building/index.md) + See [Build Documentation Locally](./local-building.md) for details. * Always run the following to fix most markdown issues in your PR @@ -96,5 +96,5 @@ that are relevant only to documentation make markdownlint-fix ``` - See [Markdownlint](../linter-requirements/index.md#markdownlint) + See [Markdownlint](./linter-requirements.md#markdownlint) for details. diff --git a/docs-new/docs/contribute/docs/source-file-structure.md b/docs-new/docs/contribute/docs/source-file-structure.md index 894230d4cf..df046089f4 100644 --- a/docs-new/docs/contribute/docs/source-file-structure.md +++ b/docs-new/docs/contribute/docs/source-file-structure.md @@ -71,7 +71,7 @@ For background information, see: #### API Reference The -[API Reference](../../../reference/api-reference/index.md) +[API Reference](../../reference/api-reference/index.md) pages are autogenerated from the source code. This is a comprehensive list of all APIs and resources Keptn uses, most of which users seldom see. @@ -97,7 +97,7 @@ in the root directory of your `lifecycle-toolkit` clone: #### CRD Reference The -[CRD Reference](../../../reference/crd-reference/index.md) +[CRD Reference](../../reference/crd-reference/index.md) pages describe the YAML files used to populate resources for the small set of CRDs that users must populate themselves. @@ -111,7 +111,7 @@ provide introductory material about how to use various features. A template to use to create a new CRD Reference page is available -[here](../templates/yaml-crd-ref-template.md). +[here](./yaml-crd-ref-template.md). ## Contributing guide @@ -150,20 +150,23 @@ leaving links to the various sections in the *CONTRIBUTING.md* guides. This section discusses how the individual files and directories are assembled into the documentation set. See -[Published Doc Structure](../publish/index.md) +[Published Doc Structure](./publish.md) for information about the branches where the documentation is published. -All files in the directories are built -except for files that are explicitly `ignored` -and files that include the `hidden: true` string in the file's metadata section. +All files in the directories are built. The order in which the files are displayed -is determined by the value of the `weight` field -in the metadata section of *_index.md*, *index.md*, -and *topic.md* files that are located throughout the directory tree. +is determined by their order in the `nav` field +of the `.mkdocs.yaml` file. -The metadata section of these files contains at least three fields. -As an example, the metadata section for the *Installation and upgrade* section -of the documentation includes the following fields: +## Subdirectory structure -```yaml +Each subdirectory contains topical subdirectories for each chapter in that section. +Each topical subdirectory may contain: + +* An *index.md* file that has the text for the section. + If this is a subdirectory that contains subdirectories for other pages, + the *index.md* file + contains introductory content for the section. +* An *assets* subdirectory where graphical files for that topic are stored. + No *assets* subdirectory is present if the topic has no graphics. \ No newline at end of file diff --git a/docs-new/docs/contribute/docs/word-list.md b/docs-new/docs/contribute/docs/word-list.md index 50cf191042..4a31a2c294 100644 --- a/docs-new/docs/contribute/docs/word-list.md +++ b/docs-new/docs/contribute/docs/word-list.md @@ -94,10 +94,10 @@ It is important to use the related terminology correctly: Most of the time, we recommend just using the term "resource". * The first occurence of a CRD name in a section should be a link to the - CRD YAML Reference under the right [component](../../../components/index.md) + CRD YAML Reference under the right [component](../../components/index.md) page if there is one. Otherwise, it should be a link to the appropriate spot in the - [API Reference](../../../reference/api-reference/index.md) + [API Reference](../../reference/api-reference/index.md) section. * Occurrences of a resource name that are not links to a reference page diff --git a/docs-new/docs/contribute/general/contrib-guidelines-gen.md b/docs-new/docs/contribute/general/contrib-guidelines-gen.md index a837f6ffba..572d436361 100644 --- a/docs-new/docs/contribute/general/contrib-guidelines-gen.md +++ b/docs-new/docs/contribute/general/contrib-guidelines-gen.md @@ -7,7 +7,7 @@ making contributions towards the repository. These guidelines are appropriate for both software and documentation. For additional guidelines that are relevant only to documentation, see -[Contribution guidelines for documentation](../../docs/contrib-guidelines-docs/index.md). +[Contribution guidelines for documentation](../docs/contrib-guidelines-docs.md). ## Guidelines for contributing diff --git a/docs-new/docs/contribute/general/git/branch-create.md b/docs-new/docs/contribute/general/git/branch-create.md index 598dcb9ded..9153197f19 100644 --- a/docs-new/docs/contribute/general/git/branch-create.md +++ b/docs-new/docs/contribute/general/git/branch-create.md @@ -1,7 +1,7 @@ # Create local branch After you -[fork and clone](../fork-clone/index.md) +[fork and clone](./fork-clone.md) the Keptn repository and set `upstream` in your local machine, you need to create a local branch where you will make your changes. @@ -34,7 +34,7 @@ then create a PR to add these changes to the documentation set. or at `localhost:1314/docs-dev` to ensure that it is rendering correctly and that all links are valid.. - See [Build Documentation Locally](../../../docs/local-building/index.md) + See [Build Documentation Locally](../../docs/local-building.md) for more information. * Run `make markdownlint-fix` to check and fix the markdown code. @@ -45,4 +45,4 @@ then create a PR to add these changes to the documentation set. When you have completed the checking and testing of your work, it is time to push your changes and create a PR that can be reviewed. -See [Create PR](../pr-create/index.md) for details. +See [Create PR](./pr-create.md) for details. diff --git a/docs-new/docs/contribute/general/git/fork-clone.md b/docs-new/docs/contribute/general/git/fork-clone.md index f1acf6e31c..cfe6a323ee 100644 --- a/docs-new/docs/contribute/general/git/fork-clone.md +++ b/docs-new/docs/contribute/general/git/fork-clone.md @@ -51,5 +51,5 @@ of the Keptn repository on your local machine: ``` You are now ready to -[create a local branch](../branch-create/index.md) +[create a local branch](./branch-create.md) and begin to create the software or documentation modifications. diff --git a/docs-new/docs/contribute/general/git/pr-create.md b/docs-new/docs/contribute/general/git/pr-create.md index 97c6d4ea65..1eadd15325 100644 --- a/docs-new/docs/contribute/general/git/pr-create.md +++ b/docs-new/docs/contribute/general/git/pr-create.md @@ -2,7 +2,7 @@ When you have completed the checking and testing of your work on your local branch as described in -[Create local branch](../branch-create/index.md), +[Create local branch](./branch-create.md), it is time to push your changes and create a PR that can be reviewed. This is a two-step process: @@ -193,4 +193,4 @@ The most common errors for documentation PRs are: When you have resolved all build errors you move into the -[PR review process](../review/index.md). +[PR review process](./review.md). diff --git a/mkdocs.yml b/mkdocs.yml index 5820e18417..0356ffc715 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -106,9 +106,9 @@ nav: - docs/components/lifecycle-operator/index.md - Flow of deployment: docs/components/lifecycle-operator/deployment-flow.md - Keptn Applications and Keptn Workloads: docs/components/lifecycle-operator/keptn-apps.md - - Metrics Operator: docs/components/metrics-operator/index.md - - Scheduler and Scheduling Gates: docs/components/scheduling/index.md - - Keptn Certificate Manager: docs/components/certificate-operator/index.md + - Metrics Operator: docs/components/metrics-operator.md + - Scheduler and Scheduling Gates: docs/components/scheduling.md + - Keptn Certificate Manager: docs/components/certificate-operator.md - Reference: - docs/reference/index.md - API Reference: @@ -148,25 +148,25 @@ nav: - docs/contribute/index.md - General information about contributing: - docs/contribute/general/index.md - - Technologies and concepts you should know: docs/contribute/general/technologies/index.md - - Codespaces: docs/contribute/general/codespace/index.md - - DCO: docs/contribute/general/dco/index.md + - Technologies and concepts you should know: docs/contribute/general/technologies.md + - Codespaces: docs/contribute/general/codespace.md + - DCO: docs/contribute/general/dco.md - Working with Git: - docs/contribute/general/git/index.md - - Fork and clone the repository: docs/contribute/general/git/fork-clone/index.md - - Create local branch: docs/contribute/general/git/branch-create/index.md - - Create PR: docs/contribute/general/git/pr-create/index.md - - PR review process: docs/contribute/general/git/review/index.md - - Contribution Guidelines: docs/contribute/general/contrib-guidelines-gen/index.md + - Fork and clone the repository: docs/contribute/general/git/fork-clone.md + - Create local branch: docs/contribute/general/git/branch-create.md + - Create PR: docs/contribute/general/git/pr-create.md + - PR review process: docs/contribute/general/git/review.md + - Contribution Guidelines: docs/contribute/general/contrib-guidelines-gen.md - Software contributions: - docs/contribute/software/index.md - - Software development environment: docs/contribute/software/dev-environ/index.md + - Software development environment: docs/contribute/software/dev-environ.md - Documentation contributions: - docs/contribute/docs/index.md - - CRD name: docs/contribute/docs/templates/yaml-crd-ref-template.md - - Contribution guidelines for documentation: docs/contribute/docs/contrib-guidelines-docs/index.md - - Build Documentation Locally: docs/contribute/docs/local-building/index.md - - Linter Requirements: docs/contribute/docs/linter-requirements/index.md - - Source File Structure: docs/contribute/docs/source-file-structure/index.md - - Published Doc Structure: docs/contribute/docs/publish/index.md - - Word list: docs/contribute/docs/word-list/index.md + - CRD name: docs/contribute/docs/yaml-crd-ref-template.md + - Contribution guidelines for documentation: docs/contribute/docs/contrib-guidelines-docs.md + - Build Documentation Locally: docs/contribute/docs/local-building.md + - Linter Requirements: docs/contribute/docs/linter-requirements.md + - Source File Structure: docs/contribute/docs/source-file-structure.md + - Published Doc Structure: docs/contribute/docs/publish.md + - Word list: docs/contribute/docs/word-list.md