diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..350d969 --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,12 @@ +name: Documentation + +on: + push: + branches: [ "main" ] + pull_request: + +jobs: + docs-checks: + uses: canonical/operator-workflows/.github/workflows/docs.yaml@main + secrets: inherit + diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index 765871a..f2afcb2 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -8,5 +8,5 @@ jobs: uses: canonical/operator-workflows/.github/workflows/test.yaml@main secrets: inherit with: - vale-style-check: true + vale-style-check: false with-uv: true diff --git a/.gitignore b/.gitignore index c326d98..99cc53e 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,16 @@ __pycache__/ *.rock .venv/ .vscode/ + +# BEGIN VALE WORKFLOW IGNORE +.vale/styles/* +!.vale/styles/local +!.vale/styles/config/ + +.vale/styles/config/* +!.vale/styles/config/vocabularies/ + +.vale/styles/config/vocabularies/* +!.vale/styles/config/vocabularies/local +# END VALE WORKFLOW IGNORE + diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 0000000..fe3518b --- /dev/null +++ b/.vale.ini @@ -0,0 +1,12 @@ +; Copyright 2025 Canonical Ltd. +; See LICENSE file for licensing details. + +StylesPath = .vale/styles + +Packages = https://github.com/canonical/platform-engineering-vale-package/releases/download/latest/pfe-vale.zip + +Vocab = PFE, local + +[*] +BasedOnStyles = PFE + diff --git a/.custom_wordlist.txt b/.vale/styles/config/vocabularies/local/accept.txt similarity index 100% rename from .custom_wordlist.txt rename to .vale/styles/config/vocabularies/local/accept.txt diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 43e9a9f..306a619 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ This document explains the processes and practices recommended for contributing - Generally, before developing enhancements to this charm, you should consider [opening an issue](https://github.com/canonical/pollen-operator/issues) explaining your use case. - If you would like to chat with us about your use-cases or proposed implementation, you can reach - us at [Canonical Mattermost public channel](https://chat.charmhub.io/charmhub/channels/charm-dev) + us at the [Canonical Matrix public channel](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) or [Discourse](https://discourse.charmhub.io/). - Familiarizing yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk) library will help you a lot when working on new features or bug fixes. @@ -19,7 +19,7 @@ This document explains the processes and practices recommended for contributing ## Developing -To make contributions to this charm, you'll need a working [development setup](https://juju.is/docs/sdk/dev-setup). +To make contributions to this charm, you'll need a working [development setup](https://documentation.ubuntu.com/juju/3.6/howto/manage-your-deployment/). The code for this charm can be downloaded as follows: diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..2db7f38 --- /dev/null +++ b/Makefile @@ -0,0 +1,41 @@ +# Copyright 2025 Canonical Ltd. +# See LICENSE file for licensing details. + +# Top-level Makefile +# Delegates targets to Makefile.docs + +# ============================================================================== +# Macros +# ============================================================================== + +# Colors +NO_COLOR=\033[0m +CYAN_COLOR=\033[0;36m +YELLOW_COLOR=\033[0;93m +RED_COLOR=\033[0;91m + +msg = @printf '$(CYAN_COLOR)$(1)$(NO_COLOR)\n' +errmsg = @printf '$(RED_COLOR)Error: $(1)$(NO_COLOR)\n' && exit 1 + +# ============================================================================== +# Core +# ============================================================================== + +include Makefile.docs + +.PHONY: help +help: _list-targets ## Prints all available targets + +.PHONY: _list-targets +_list-targets: ## This collects and prints all targets, ignore internal commands + $(call msg,Available targets:) + @awk -F'[:#]' ' \ + /^[a-zA-Z0-9._-]+:([^=]|$$)/ { \ + target = $$1; \ + comment = ""; \ + if (match($$0, /## .*/)) \ + comment = substr($$0, RSTART + 3); \ + if (target != ".PHONY" && target !~ /^_/ && !seen[target]++) \ + printf " make %-20s $(YELLOW_COLOR)# %s$(NO_COLOR)\n", target, comment; \ + }' $(MAKEFILE_LIST) | sort + diff --git a/Makefile.docs b/Makefile.docs new file mode 100644 index 0000000..213ec01 --- /dev/null +++ b/Makefile.docs @@ -0,0 +1,75 @@ +# Copyright 2025 Canonical Ltd. +# See LICENSE file for licensing details. + +# Minimal makefile for documentation +# + +# Vale settings +VALE_DIR ?= .vale +PRAECEPTA_CONFIG ?= .vale.ini +DOCS_FILES ?= docs/ README.md CONTRIBUTING.md + +HAS_VALE := $(shell command -v vale;) +HAS_LYCHEE := $(shell command -v lychee;) + +# ============================================================================== +# Docs Targets +# ============================================================================== + +.PHONY: docs-check +docs-check: vale lychee ## Run all Docs checks + +.PHONY: docs-clean +docs-clean: vale-clean + +# ============================================================================== +# Dependency Check Targets +# ============================================================================== + +.PHONY: .check-vale +.check-vale: +ifndef HAS_VALE + $(call errmsg,'vale' is not installed. Please install it first) \ + exit 1; +endif + +.PHONY: .check-lychee +.check-lychee: +ifndef HAS_LYCHEE + $(call errmsg,'lychee' is not installed. Please install it first) \ + exit 1; +endif + + +# ============================================================================== +# Main Vale Targets +# ============================================================================== + +.PHONY: vale-sync +vale-sync: ## Download and install external Vale configuration sources + $(call msg,--- Syncing Vale styles... ---) + @vale sync + +.PHONY: vale +vale: .check-vale vale-sync ## Run Vale checks on docs + $(call msg,--- Running Vale checks on "$(DOCS_FILES)"... ---) + @vale --config=$(PRAECEPTA_CONFIG) $(DOCS_FILES) + +# ============================================================================== +# Main Lychee Targets +# ============================================================================== + +.PHONY: lychee +lychee: .check-lychee ## Run Lychee checks on docs + $(call msg,--- Running lychee checks on "$(LYCHEE_DOCS_FILES)"... ---) + @lychee $(DOCS_FILES) + +# ============================================================================== +# Helper Targets +# ============================================================================== + +.PHONY: vale-clean +vale-clean: + $(call msg,--- Cleaning downloaded packages and ignored files from "$(VALE_DIR)"... ---) + @git clean -dfX $(VALE_DIR) + diff --git a/docs/explanation/charm-architecture.md b/docs/explanation/charm-architecture.md index c38768f..5de089b 100644 --- a/docs/explanation/charm-architecture.md +++ b/docs/explanation/charm-architecture.md @@ -4,7 +4,7 @@ This charm does not use an OCI image, as it runs directly on a machine rather than in a container. The charm uses the [pollen](https://github.com/canonical/pollen/blob/main/snap/snapcraft.yaml) [snap](https://ubuntu.com/core/docs/snaps-in-ubuntu-core) to install Pollen during deployment. -Canonical provides a Pollen server as a service to the Ubuntu community at [https://entropy.ubuntu.com](https://entropy.ubuntu.com). +Canonical provides a Pollen server as a service to the Ubuntu community at `https://entropy.ubuntu.com`. ## Metrics diff --git a/docs/reference/external-access.md b/docs/reference/external-access.md index 63397c1..0ce0014 100644 --- a/docs/reference/external-access.md +++ b/docs/reference/external-access.md @@ -1,4 +1,4 @@ ## External access In order for the [Pollen](https://charmhub.io/pollen) charm to work correctly, -it needs access to the [Snap Store's API](api.snapcraft.io) to download Pollen's snap. \ No newline at end of file +it needs access to the [Snap Store's API](https://api.snapcraft.io/) to download Pollen's snap. \ No newline at end of file