From a36c99d2e2dae0c0372910b9e50ea08fbd0816e6 Mon Sep 17 00:00:00 2001 From: dushu Date: Wed, 17 Apr 2024 15:16:11 -0600 Subject: [PATCH 1/2] docs: update the documentation --- .markdownlint.yaml | 272 ++++++++++++++++++++++++++++++++++++++++ .pre-commit-config.yaml | 12 +- CONTRIBUTING.md | 48 +++---- README.md | 29 +++-- metadata.yaml | 2 + 5 files changed, 325 insertions(+), 38 deletions(-) create mode 100644 .markdownlint.yaml diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 00000000..166bb70f --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,272 @@ +# Example markdownlint configuration with all properties set to their default value + +# Default state for all rules +default: true + +# Path to configuration file to extend +extends: null + +# MD001/heading-increment : Heading levels should only increment by one level at a time : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md001.md +MD001: true + +# MD003/heading-style : Heading style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md003.md +MD003: + # Heading style + style: "consistent" + +# MD004/ul-style : Unordered list style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md004.md +MD004: + # List style + style: "consistent" + +# MD005/list-indent : Inconsistent indentation for list items at the same level : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md005.md +MD005: true + +# MD007/ul-indent : Unordered list indentation : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md007.md +MD007: + # Spaces for indent + indent: 2 + # Whether to indent the first level of the list + start_indented: false + # Spaces for first level indent (when start_indented is set) + start_indent: 2 + +# MD009/no-trailing-spaces : Trailing spaces : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md009.md +MD009: + # Spaces for line break + br_spaces: 2 + # Allow spaces for empty lines in list items + list_item_empty_lines: false + # Include unnecessary breaks + strict: false + +# MD010/no-hard-tabs : Hard tabs : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md010.md +MD010: + # Include code blocks + code_blocks: true + # Fenced code languages to ignore + ignore_code_languages: [] + # Number of spaces for each hard tab + spaces_per_tab: 1 + +# MD011/no-reversed-links : Reversed link syntax : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md011.md +MD011: true + +# MD012/no-multiple-blanks : Multiple consecutive blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md012.md +MD012: + # Consecutive blank lines + maximum: 1 + +# MD013/line-length : Line length : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md013.md +MD013: + # Number of characters + line_length: 80 + # Number of characters for headings + heading_line_length: 80 + # Number of characters for code blocks + code_block_line_length: 80 + # Include code blocks + code_blocks: false + # Include tables + tables: false + # Include headings + headings: false + # Strict length checking + strict: false + # Stern length checking + stern: false + +# MD014/commands-show-output : Dollar signs used before commands without showing output : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md014.md +MD014: true + +# MD018/no-missing-space-atx : No space after hash on atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md018.md +MD018: true + +# MD019/no-multiple-space-atx : Multiple spaces after hash on atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md019.md +MD019: true + +# MD020/no-missing-space-closed-atx : No space inside hashes on closed atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md020.md +MD020: true + +# MD021/no-multiple-space-closed-atx : Multiple spaces inside hashes on closed atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md021.md +MD021: true + +# MD022/blanks-around-headings : Headings should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md022.md +MD022: + # Blank lines above heading + lines_above: 1 + # Blank lines below heading + lines_below: 1 + +# MD023/heading-start-left : Headings must start at the beginning of the line : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md023.md +MD023: true + +# MD024/no-duplicate-heading : Multiple headings with the same content : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md024.md +MD024: + # Only check sibling headings + siblings_only: false + +# MD025/single-title/single-h1 : Multiple top-level headings in the same document : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md025.md +MD025: + # Heading level + level: 1 + # RegExp for matching title in front matter + front_matter_title: "^\\s*title\\s*[:=]" + +# MD026/no-trailing-punctuation : Trailing punctuation in heading : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md026.md +MD026: + # Punctuation characters + punctuation: ".,;:!。，；：！" + +# MD027/no-multiple-space-blockquote : Multiple spaces after blockquote symbol : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md027.md +MD027: true + +# MD028/no-blanks-blockquote : Blank line inside blockquote : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md028.md +MD028: true + +# MD029/ol-prefix : Ordered list item prefix : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md029.md +MD029: + # List style + style: "one_or_ordered" + +# MD030/list-marker-space : Spaces after list markers : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md030.md +MD030: + # Spaces for single-line unordered list items + ul_single: 1 + # Spaces for single-line ordered list items + ol_single: 1 + # Spaces for multi-line unordered list items + ul_multi: 1 + # Spaces for multi-line ordered list items + ol_multi: 1 + +# MD031/blanks-around-fences : Fenced code blocks should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md031.md +MD031: + # Include list items + list_items: true + +# MD032/blanks-around-lists : Lists should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md032.md +MD032: true + +# MD033/no-inline-html : Inline HTML : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md033.md +MD033: + # Allowed elements + allowed_elements: [] + +# MD034/no-bare-urls : Bare URL used : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md034.md +MD034: true + +# MD035/hr-style : Horizontal rule style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md035.md +MD035: + # Horizontal rule style + style: "consistent" + +# MD036/no-emphasis-as-heading : Emphasis used instead of a heading : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md036.md +MD036: + # Punctuation characters + punctuation: ".,;:!?。，；：！？" + +# MD037/no-space-in-emphasis : Spaces inside emphasis markers : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md037.md +MD037: true + +# MD038/no-space-in-code : Spaces inside code span elements : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md038.md +MD038: true + +# MD039/no-space-in-links : Spaces inside link text : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md039.md +MD039: true + +# MD040/fenced-code-language : Fenced code blocks should have a language specified : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md040.md +MD040: + # List of languages + allowed_languages: [] + # Require language only + language_only: false + +# MD041/first-line-heading/first-line-h1 : First line in a file should be a top-level heading : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md041.md +MD041: + # Heading level + level: 1 + # RegExp for matching title in front matter + front_matter_title: "^\\s*title\\s*[:=]" + +# MD042/no-empty-links : No empty links : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md042.md +MD042: true + +# MD043/required-headings : Required heading structure : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md043.md +# MD043: + # List of headings + # headings: [] + # Match case of headings + # match_case: false + +# MD044/proper-names : Proper names should have the correct capitalization : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md044.md +MD044: + # List of proper names + names: [] + # Include code blocks + code_blocks: true + # Include HTML elements + html_elements: true + +# MD045/no-alt-text : Images should have alternate text (alt text) : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md045.md +MD045: true + +# MD046/code-block-style : Code block style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md046.md +MD046: + # Block style + style: "consistent" + +# MD047/single-trailing-newline : Files should end with a single newline character : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md047.md +MD047: true + +# MD048/code-fence-style : Code fence style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md048.md +MD048: + # Code fence style + style: "consistent" + +# MD049/emphasis-style : Emphasis style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md049.md +MD049: + # Emphasis style + style: "consistent" + +# MD050/strong-style : Strong style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md050.md +MD050: + # Strong style + style: "consistent" + +# MD051/link-fragments : Link fragments should be valid : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md051.md +MD051: true + +# MD052/reference-links-images : Reference links and images should use a label that is defined : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md052.md +MD052: + # Include shortcut syntax + shortcut_syntax: false + +# MD053/link-image-reference-definitions : Link and image reference definitions should be needed : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md053.md +MD053: + # Ignored definitions + ignored_definitions: + - "//" + +# MD054/link-image-style : Link and image style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md054.md +MD054: + # Allow autolinks + autolink: true + # Allow inline links and images + inline: true + # Allow full reference links and images + full: true + # Allow collapsed reference links and images + collapsed: true + # Allow shortcut reference links and images + shortcut: true + # Allow URLs as inline links + url_inline: true + +# MD055/table-pipe-style : Table pipe style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md055.md +MD055: + # Table pipe style + style: "consistent" + +# MD056/table-column-count : Table column count : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md056.md +MD056: true diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 0da10afa..5c8d9515 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,6 +1,6 @@ repos: - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.5.0 + rev: v4.6.0 hooks: - id: check-added-large-files - id: debug-statements @@ -9,18 +9,22 @@ repos: - id: requirements-txt-fixer - id: trailing-whitespace - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.1.14 + rev: v0.3.7 hooks: - id: ruff args: [--fix, --exit-non-zero-on-fix] - repo: https://github.com/psf/black - rev: 23.12.1 + rev: 24.4.0 hooks: - id: black - repo: https://github.com/pre-commit/mirrors-mypy - rev: v1.8.0 + rev: v1.9.0 hooks: - id: mypy args: ["--config-file", "pyproject.toml"] additional_dependencies: - types-PyYAML +- repo: https://github.com/igorshubovych/markdownlint-cli + rev: v0.39.0 + hooks: + - id: markdownlint diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 32fcfb2a..7249cda5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,9 +19,9 @@ this operator. will help you a lot when working on new features or bug fixes. - All enhancements require review before being merged. Code review typically examines - - code quality - - test coverage - - user experience for Juju administrators of this charm. + - code quality + - test coverage + - user experience for Juju administrators of this charm. - Please help us out in ensuring easy to review branches by rebasing your pull request branch onto the `main` branch. This also avoids merge commits and creates a linear Git @@ -33,18 +33,18 @@ You can use the environments created by `tox` for development. It helps install `pre-commit` and `mypy` type checker. ```shell -$ tox -e dev -$ source .tox/unit/bin/activate +tox -e dev +source .tox/dev/bin/activate ``` ## Testing ```shell -$ tox -e fmt # update your code according to linting rules -$ tox -e lint # code style -$ tox -e unit # unit tests -$ tox -e integration # integration tests -$ tox # runs 'fmt', 'lint', and 'unit' environments +tox -e fmt # update your code according to linting rules +tox -e lint # code style +tox -e unit # unit tests +tox -e integration # integration tests +tox # runs 'fmt', 'lint', and 'unit' environments ``` ## Build the charm @@ -52,20 +52,20 @@ $ tox # runs 'fmt', 'lint', and 'unit' environments Build the charm using: ```shell -$ charmcraft pack +charmcraft pack ``` ## Deploy the charm ```shell # Create a juju model -$ juju add-model dev +juju add-model dev # Enable DEBUG logging -$ juju model-config logging-config="=INFO;unit=DEBUG" +juju model-config logging-config="=INFO;unit=DEBUG" # Deploy the charm -$ juju deploy ./glauth-k8s_ubuntu-*-amd64.charm --resource oci-image=$(yq eval '.resources.oci-image.upstream-source' metadata.yaml) +juju deploy ./glauth-k8s_ubuntu-*-amd64.charm --resource oci-image=$(yq eval '.resources.oci-image.upstream-source' metadata.yaml) ``` ## Observability @@ -78,30 +78,30 @@ and visualize telemetry signals generated by the charmed operator. ```shell # Create a Juju model -$ juju add-model cos +juju add-model cos # Switch to the created model -$ juju switch cos +juju switch cos # Deploy the cos-lite bundle -$ juju deploy cos-lite --trust +juju deploy cos-lite --trust # Offer the endpoints in the cos-lite bundle -$ juju offer prometheus:metrics-endpoint -$ juju offer loki:logging -$ juju offer grafana:grafana-dashboard +juju offer prometheus:metrics-endpoint +juju offer loki:logging +juju offer grafana:grafana-dashboard ``` ### Integrate with COS-lite bundle ```shell # Switch to the model where glauth-k8s lives -$ juju switch +juju switch # Integrate with the observability endpoints -$ juju integrate glauth-k8s admin/cos.prometheus -$ juju integrate glauth-k8s admin/cos.loki -$ juju integrate glauth-k8s admin/cos.grafana +juju integrate glauth-k8s admin/cos.prometheus +juju integrate glauth-k8s admin/cos.loki +juju integrate glauth-k8s admin/cos.grafana ``` ## Canonical Contributor Agreement diff --git a/README.md b/README.md index a3d77e39..681367fd 100644 --- a/README.md +++ b/README.md @@ -14,20 +14,29 @@ for [GLAuth](https://github.com/glauth/glauth), an open-sourced LDAP server. ## Usage -The GLAuth charmed operator can be deployed using the following command: +The `glauth-k8s` charmed operator can be deployed using the following command: ```shell -$ juju deploy glauth-k8s --channel edge --trust +juju deploy glauth-k8s --channel edge --trust ``` -The GLAuth charmed operator uses +The `glauth-k8s` charmed operator uses the [Charmed PostgreSQL K8s Operator](https://github.com/canonical/postgresql-k8s-operator) as the backend: ```shell -$ juju deploy postgresql-k8s --channel stable --trust +juju deploy postgresql-k8s --channel 14/stable --trust -$ juju integrate glauth-k8s postgresql-k8s +juju integrate glauth-k8s postgresql-k8s +``` + +The `glauth-k8s` charmed operator also requires a certificate provider. Take +the `self-signed-certificates-operator` as an example: + +```shell +juju deploy self-signed-certificates --channel stable --trust + +juju integrate glauth-k8s self-signed-certificates ``` ## Integrations @@ -39,7 +48,7 @@ LDAP client charmed operator following the [`ldap` interface protocol](https://github.com/canonical/charm-relation-interfaces/tree/main/interfaces/ldap/v0). ```shell -$ juju integrate :ldap glauth-k8s:ldap +juju integrate :ldap glauth-k8s:ldap ``` ### `glauth_auxiliary` Integration @@ -50,7 +59,7 @@ the [`glauth-utils` charmed operator](https://github.com/canonical/glauth-utils) to deliver necessary auxiliary configurations. ```shell -$ juju integrate glauth-utils glauth-k8s +juju integrate glauth-utils glauth-k8s ``` ### `certificate_transfer` Integration @@ -60,7 +69,7 @@ integration with any charmed operator following the [`certificate_transfer` interface protocol](https://github.com/canonical/charm-relation-interfaces/tree/main/interfaces/certificate_transfer/v0). ```shell -$ juju integrate glauth-k8s +juju integrate glauth-k8s ``` ### `postgresql_client` Integration @@ -70,7 +79,7 @@ The `glauth-k8s` charmed operator requires the integration with the protocol](https://github.com/canonical/charm-relation-interfaces/tree/main/interfaces/postgresql_client/v0). ```shell -$ juju integrate glauth-k8s postgresql-k8s +juju integrate glauth-k8s postgresql-k8s ``` ### `tls_certificates` Integration @@ -81,7 +90,7 @@ interface protocol](https://github.com/canonical/charm-relation-interfaces/tree/ Take the `self-signed-certificates-operator` as an example: ```shell -$ juju integrate glauth-k8s self-signed-certificates +juju integrate glauth-k8s self-signed-certificates ``` ## Configurations diff --git a/metadata.yaml b/metadata.yaml index 6850b73b..11072498 100644 --- a/metadata.yaml +++ b/metadata.yaml @@ -9,6 +9,8 @@ description: | summary: | LDAP authentication provider +doc: https//discourse.charmhub.io/t/13946 + containers: glauth: resource: oci-image From 0abc9ddf3d7d6faecae876debfc037f1dadf7809 Mon Sep 17 00:00:00 2001 From: dushu Date: Thu, 18 Apr 2024 10:23:36 -0600 Subject: [PATCH 2/2] resolve comments --- lint-requirements.txt | 1 + metadata.yaml | 2 +- tox.ini | 3 +++ 3 files changed, 5 insertions(+), 1 deletion(-) diff --git a/lint-requirements.txt b/lint-requirements.txt index 0943b53e..0a78334f 100644 --- a/lint-requirements.txt +++ b/lint-requirements.txt @@ -1,3 +1,4 @@ black codespell +pre-commit ruff diff --git a/metadata.yaml b/metadata.yaml index 11072498..2eb465e0 100644 --- a/metadata.yaml +++ b/metadata.yaml @@ -9,7 +9,7 @@ description: | summary: | LDAP authentication provider -doc: https//discourse.charmhub.io/t/13946 +docs: https://discourse.charmhub.io/t/13946 containers: glauth: diff --git a/tox.ini b/tox.ini index 6f177262..1d51145d 100644 --- a/tox.ini +++ b/tox.ini @@ -58,6 +58,9 @@ commands = ruff {[vars]all_path} black --check --diff {[vars]all_path} + pre-commit install + pre-commit autoupdate + [testenv:unit] description = Run unit tests deps =