diff --git a/.github/workflows/docs-publish.yaml b/.github/workflows/docs-publish.yaml new file mode 100644 index 0000000..0fb9a9f --- /dev/null +++ b/.github/workflows/docs-publish.yaml @@ -0,0 +1,44 @@ +name: Build and publish documentation to GitHub Pages + +on: + push: + branches: + - feature/* + - master +# tags: +# - 'v[0-9]+.[0-9]+.[0-9]+' + +jobs: + build: + runs-on: ubuntu-22.04 +# container: +# image: python:3.9 + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Install Python dependencies + run: pip install -r docs/requirements.txt + + - name: Build, validate documentation using MkDocs + run: | +# git config --global --add safe.directory /__w/rmk/rmk + mkdocs build --verbose --clean --strict + rm -r site/ + + - name: Configure Git +# if: startsWith(github.ref, 'refs/tags/') + id: git-configuration + run: | + echo "Configure Git user.name and user.email." + git config user.name github-actions + git config user.email github-actions@github.com + + echo tag=${GITHUB_REF#refs/tags/} >> "${GITHUB_OUTPUT}" + + - name: Build, publish, version documentation using Mike +# if: startsWith(github.ref, 'refs/tags/') + run: | +# mike deploy --update-aliases --push --rebase ${{ steps.git-configuration.outputs.tag }} latest diff --git a/README.md b/README.md index d58d6c9..177b7e0 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,7 @@ Command line tool for reduced management and provisioning of Kubernetes clusters * [Supported Kubernetes providers](#supported-kubernetes-providers) * [Roadmap](#roadmap) * [License](#license) + * [Code of Conduct](#code-of-conduct) ## Overview @@ -194,3 +195,9 @@ Check the [issues](https://github.com/edenlabllc/rmk/issues) for more informatio ## License RMK is open source software (OSS) licensed under the [Apache 2.0 License](LICENSE). + +## Code of Conduct + +This project adheres to the Contributor Covenant [Сode of Сonduct](https://github.com/edenlabllc/rmk/blob/develop/docs/CODE_OF_CONDUCT.md). +By participating, you are expected to uphold this code. +Please refer to our [Contributing Guidelines](https://github.com/edenlabllc/rmk/blob/develop/docs/CONTRIBUTING.md) for further information. diff --git a/docs/.pages b/docs/.pages new file mode 100644 index 0000000..d04de88 --- /dev/null +++ b/docs/.pages @@ -0,0 +1,5 @@ +nav: + - index.md + - quickstart.md + - configuration +collapse: false diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 0000000..3c1c2db --- /dev/null +++ b/docs/CNAME @@ -0,0 +1 @@ +rmk.io diff --git a/docs/commands.md b/docs/commands.md index 068b1cb..e2b2ec6 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -74,7 +74,7 @@ K3D cluster management Create K3D cluster -**--k3d-volume-host-path, --kv**="": host local directory path for mount into K3D cluster (default: "${PWD}/rmk.tools.infra") +**--k3d-volume-host-path, --kv**="": host local directory path for mount into K3D cluster (default: "${PWD}/rmk") #### delete, d diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..c4b62f7 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,8 @@ +# RMK Documentation + +Hi! You are welcomed to RMK onboard! +This document is useful for beginners and for advanced DevOps specialists. + +Let’s deep dive into fabolous DevOps world with RMK. + +Yours, RMK Team. diff --git a/docs/quickstart.md b/docs/quickstart.md index 6f9b031..192a990 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -6,8 +6,9 @@ create a local cluster based on `K3D`, deploy your first application ([Nginx](ht > Prerequisite: > - An active AWS user with access keys and the `AdministratorAccess` permissions. > - A prepared [project repository](configuration/project-management/preparation-of-project-repository.md#preparation-of-the-project-repository) -> - Installed [RMK](../README.md#installation) -> - The fulfilled [requirements](../README.md#requirements) for proper RMK operation. + +[//]: # (> - Installed [RMK](../README.md#installation)) +[//]: # (> - The fulfilled [requirements](../README.md#requirements) for proper RMK operation.) 0. Create a [project.yaml](configuration/project-management/preparation-of-project-repository.md#projectyaml) file in the root of the project repository with the following content: @@ -103,7 +104,7 @@ inventory: 3. Create a local K3D cluster: - > Before running this step, ensure that Docker is installed in the system according to the [requirements](../README.md#requirements). +[//]: # ( > Before running this step, ensure that Docker is installed in the system according to the [requirements](../README.md#requirements).) ```shell rmk cluster k3d create diff --git a/docs/release-notes.md b/docs/release-notes.md index 8a638b7..7d9a36d 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -1,3 +1 @@ -- #18 - Fixed links to the OSS repository in project generation. -- #18 - Split the issue template into the bug and feature templates. -- #18 - Updated the Roadmap section of README.md. +- #27 Configured GitHub Pages documentation generation using MkDocs diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..c2a4eaa --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,8 @@ +mkdocs==1.5.3 +mkdocs-material==9.4.6 +pymdown-extensions==10.3.1 +mkdocs-git-revision-date-localized-plugin==1.2.1 +mkdocs-awesome-pages-plugin==2.9.2 +mdx_truly_sane_lists==1.3 # https://github.com/radude/mdx_truly_sane_lists +mkdocs-include-markdown-plugin==6.0.3 # https://github.com/mondeja/mkdocs-include-markdown-plugin +mike==1.1.2 # versioned docs: https://github.com/jimporter/mike diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..d33a714 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,101 @@ +# Project information +site_name: RMK +site_description: RMK CLI - Reduced Management for Kubernetes by Edenlab LLC. +# todo change to static domain +site_url: https://edenlabllc.github.io/rmk + +copyright: © EDENLAB. ALL RIGHTS RESERVED, 2021 - 2024 + +# Extra Files +extra_javascript: + - static/js/asciinema-player.js + +extra_css: + - static/css/asciinema-player.css + - static/css/extra.css + +# Repo Information +repo_name: edenlabllc/rmk +repo_url: https://github.com/edenlabllc/rmk + +# Edit Link on Site +#edit_uri: edit/main/docs/ + +# Theme +theme: + name: material + language: en + features: + - navigation.top # show back to top button + - search.suggest # search suggestions: https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-suggestions + - search.highlight # highlight search term on target page: https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-suggestions + - navigation.expand + - navigation.tabs + - navigation.tabs.sticky # stick navigation tabs below header while scrolling + - navigation.tracking + - navigation.path +# todo review list of features +# - navigation.instant +# - navigation.sections +# - navigation.indexes + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: "black" + accent: "grey" + toggle: + icon: material/toggle-switch-off-outline + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: light blue + toggle: + icon: material/toggle-switch + name: Switch to light mode + # todo change icons and logo + logo: https://edenlab.io/wp-content/themes/edenlab/assets/images/fhir_icon.svg + favicon: https://edenlab.io/favicon.ico + icon: + repo: fontawesome/brands/github + +# Navigation +# nav: omitted, because we're using the awesome-pages plugin (https://squidfunk.github.io/mkdocs-material/plugins/awesome-pages/) + +# Extensions +markdown_extensions: + - attr_list + - toc: + permalink: true + - admonition # https://squidfunk.github.io/mkdocs-material/extensions/admonition/ + - pymdownx.highlight: # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#highlight + use_pygments: true + - pymdownx.inlinehilite # https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#inlinehilite + - pymdownx.superfences # https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#superfences + - pymdownx.tabbed # https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#tabbed + - pymdownx.details # https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#details + - pymdownx.emoji: # https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#configuration + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - smarty # https://python-markdown.github.io/extensions/smarty/ + - mdx_truly_sane_lists # https://github.com/radude/mdx_truly_sane_lists -> proper indentation of md list items + +# Plugins +plugins: + - search + - git-revision-date-localized: # https://squidfunk.github.io/mkdocs-material/plugins/revision-date/ + type: date + - awesome-pages # https://squidfunk.github.io/mkdocs-material/plugins/awesome-pages/ + - include-markdown # https://github.com/mondeja/mkdocs-include-markdown-plugin + - mike: # Versioned Docs: https://github.com/jimporter/mike + version_selector: true # set to false to leave out the version selector + css_dir: static/css # the directory to put the version selector's CSS + javascript_dir: static/js # the directory to put the version selector's JS + canonical_version: null # the version for ; `null` uses the version specified via `mike deploy` + +# Extra mkdocs-material settings +extra: + version: + provider: mike + +# Other Settings +strict: true # halt processing when a warning is raised