-
Notifications
You must be signed in to change notification settings - Fork 126
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
7 changed files
with
196 additions
and
151 deletions.
There are no files selected for viewing
This file contains 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,26 @@ | ||
| #!/bin/bash | ||
|
|
||
| # Keptn Lifecycle Toolkit Documentation generation | ||
| # | ||
| # This script supports the release of the latest version of the documentation | ||
| # The final files are available under the docs/release folder | ||
|
|
||
| SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" | ||
| ROOT_DIR=${SCRIPT_DIR/.github\/scripts/} | ||
| DOC_DIR="${ROOT_DIR}docs" | ||
| WORK_DIR=${DOC_DIR}/release | ||
|
|
||
| ## Create the working folder | ||
| mkdir -p $WORK_DIR | ||
|
|
||
| cd $WORK_DIR | ||
|
|
||
| ## Download the latest status of the main documentation | ||
| git clone https://github.com/keptn/lifecycle-toolkit.git | ||
| cd lifecycle-toolkit | ||
| git checkout page | ||
| git pull | ||
|
|
||
| ## Rewrite with the current content | ||
| cp -r "${DOC_DIR}/content/en/docs" ./docs/content/en | ||
|
|
This file contains 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
This file contains 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
This file contains 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
This file contains 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -38,5 +38,5 @@ menu: | |
| - name: Keptn v1 | ||
| params: | ||
| rel: external | ||
| url: https://keptn.sh/ | ||
| url: https://v1.keptn.sh/ | ||
| weight: 1 | ||
101 changes: 101 additions & 0 deletions
101
docs/content/en/contribute/docs/linter-requirements/_index.md
This file contains 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,101 @@ | ||
| --- | ||
| title: Linter Requirements | ||
| description: To maintain optimal code quality, this project employs linters which require a specific IDE configuration for effective utilization. | ||
| weight: 400 | ||
| --- | ||
|
|
||
| ## Linter Requirements | ||
|
|
||
| This project uses a set of linters to ensure good code quality. | ||
| In order to make proper use of those linters inside an IDE, | ||
| the following configuration is required. | ||
|
|
||
| ### Golangci-lint | ||
|
|
||
| Further information can also be found in | ||
| the [`golangci-lint` documentation](https://golangci-lint.run/usage/integrations/). | ||
|
|
||
| #### Visual Studio Code | ||
|
|
||
| In Visual Studio Code the | ||
| [Golang](https://marketplace.visualstudio.com/items?itemName=aldijav.golangwithdidi) | ||
| extension is required. | ||
|
|
||
| Adding the following lines to the `Golang` extension | ||
| configuration file enables all linters used in this project. | ||
|
|
||
| ```json | ||
| "go.lintTool": { | ||
| "type": "string", | ||
| "default": "golangci-lint", | ||
| "description": "GolangGCI Linter", | ||
| "scope": "resource", | ||
| "enum": [ | ||
| "golangci-lint", | ||
| ] | ||
| }, | ||
| "go.lintFlags": { | ||
| "type": "array", | ||
| "items": { | ||
| "type": "string" | ||
| }, | ||
| "default": ["--fast", "--fix"], | ||
| "description": "Flags to pass to GCI Linter", | ||
| "scope": "resource" | ||
| }, | ||
| ``` | ||
|
|
||
| #### GoLand / IntelliJ requirements | ||
|
|
||
| * Install either the **GoLand** or **IntelliJ** Integrated Development Environment | ||
| (IDE) for the Go programming language, plus the [Go Linter](https://plugins.jetbrains.com/plugin/12496-go-linter) plugin. | ||
|
|
||
| * The plugin can be installed via `Settings` >> `Plugins` >> `Marketplace`, | ||
| search for `Go Linter` and install it. | ||
| Once installed, make sure that the plugin is using the `.golangci.yml` | ||
| file from the root directory. | ||
|
|
||
| * The configuration of `Go Linter` can be found in the `Tools` section | ||
| of the settings. | ||
|
|
||
| If you are on Windows, you need to install **make** for the above process to complete. | ||
|
|
||
| > **Note** | ||
| When using the make command on Windows, you may receive an `unrecognized command` error for a command that is installed. | ||
| This usually indicates that `PATH` for the binary is not set correctly). | ||
|
|
||
| ### Markdownlint | ||
|
|
||
| We are using [markdownlint](https://github.com/DavidAnson/markdownlint) to ensure consistent styling | ||
| within our Markdown files. | ||
| Specifically we are using [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli). | ||
|
|
||
| We are using `GNU MAKE` to ensure the same functionality locally and within our CI builds. | ||
| This should allow easier debugging and problem resolution. | ||
|
|
||
| #### Markdownlint execution | ||
|
|
||
| To verify that your markdown code conforms to the rules, run the following on your local branch: | ||
|
|
||
| ```shell | ||
| make markdownlint | ||
| ``` | ||
|
|
||
| To use the auto-fix option, run: | ||
|
|
||
| ```shell | ||
| make markdownlint-fix | ||
| ``` | ||
|
|
||
| #### Markdownlint Configuration | ||
|
|
||
| We use the default configuration values for `markdownlint`. | ||
|
|
||
| This means: | ||
|
|
||
| [.markdownlint-cli2.yaml](https://github.com/keptn/lifecycle-toolkit/blob/main/.markdownlint-cli2.yaml) | ||
| contains the rule configuration | ||
|
|
||
| We use the default values, so tools like | ||
| [markdownlint for VSCode](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) | ||
| can be used without additional configuration. |
61 changes: 61 additions & 0 deletions
61
docs/content/en/contribute/docs/source-file-structure/_index.md
This file contains 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,61 @@ | ||
| --- | ||
| title: Source File Structure | ||
| description: Structure source files with Metadata | ||
| weight: 400 | ||
| --- | ||
|
|
||
| The source files for the [Keptn Lifecycle Toolkit](https://lifecycle.keptn.sh/docs) are stored under | ||
| the *docs/content/en/docs* directory in the repository. | ||
| The build strategy is to build everything except for files that are explicitly ignored | ||
| and files that include the `hidden: true` string in the file's metadata section | ||
|
|
||
| The order in which the files are displayed is determined by the value of the `weight` field | ||
| in the metadata section of *_index.md* and *index.md* files located throughout the directory tree. | ||
|
|
||
| The metadata section of these files contains at least three fields. | ||
| As an example, the metadata section for the *Concepts* section of the documentation includes the following fields: | ||
|
|
||
| ```yaml | ||
| title: Concepts | ||
| description: Learn about underlying concepts of the keptn lifecycle toolkit. | ||
| icon: concepts | ||
| layout: quickstart | ||
| weight: 50 | ||
| ``` | ||
| The meaning of these fields is: | ||
| * **title** -- title displayed for the section or file | ||
| * **description** -- subtext displayed for the section or subsection | ||
| * **weight** -- order in which section or subsection is displayed relative to other sections and | ||
| subsections at the same level. | ||
| In this case, the weight of 50 means that this section is displayed | ||
| after sections that have weights of 49 and lower | ||
| and before sections that have weights of 51 and higher. | ||
| If two files have the same weight, | ||
| their order is determined alphabetically, | ||
| but this is a bad practice. | ||
| Some other fields are sometimes used in the metadata. | ||
| ### Top level structure | ||
| The current tools do not support versioning. | ||
| To work around this limitation, the docs are arranged with some general topics that generally apply to all releases and | ||
| then subsections for each release that is currently supported. | ||
| The system for assigning weights for the docs landing page is: | ||
| * General introductory material uses weight values under 100. | ||
| * Sections for individual releases use weight values of 9**. | ||
| * Sections for general but advanced info use weight value of 1***. | ||
| ### Subdirectory structure | ||
| Each subdirectory contains topical subdirectories for each chapter in that section. | ||
| Each topical subdirectory contains: | ||
| * An *index.md* file that has the metadata discussed above plus the text 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. |