docs: populate charm documentation (#6)

* feat: set up charm skeleton

* feat: add more charm hooks

* test: add unit test cases

* docs: update readme and tox lint

* fix tox problems

* fix lint error

* test: add integration test

* fix charmcraft.yaml

* docs: update charm docs

* docs: update contributing and index

* docs: add actions, config, integrate

* add documentation workflows

* fix capitalisation

Co-authored-by: Erin Conley <erin.conley@canonical.com>

* Apply suggestions from code review

Co-authored-by: Erin Conley <erin.conley@canonical.com>

* apply suggestions

* fix vale complaints

* Apply suggestions from code review

Co-authored-by: Erin Conley <erin.conley@canonical.com>

* apply suggestion

* Update README.md

Co-authored-by: Erin Conley <erin.conley@canonical.com>

* Apply suggestions from code review

Co-authored-by: Erin Conley <erin.conley@canonical.com>

* update docs

* fix vale

* Apply suggestions from code review

Co-authored-by: Erin Conley <erin.conley@canonical.com>

* remove section

* update badges

* Update docs/how-to/configure.md

Co-authored-by: Weii Wang <weii.wang@canonical.com>

* fix description

---------

Co-authored-by: erinecon <erin.conley@canonical.com>
Co-authored-by: Weii Wang <weii.wang@canonical.com>

Author: 3 people

.github/workflows/comment.yaml

@@ -10,3 +10,4 @@ jobs:
   comment-on-pr:
     uses: canonical/operator-workflows/.github/workflows/comment.yaml@main
     secrets: inherit
+

.github/workflows/docs.yaml

@@ -0,0 +1,11 @@
+name: Documentation
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+
+jobs:
+  docs-checks:
+    uses: canonical/operator-workflows/.github/workflows/docs.yaml@main
+    secrets: inherit

.gitignore

@@ -11,3 +11,16 @@ __pycache__/
 *.egg-info/
 */*.rock
 terraform/tests/.terraform
+
+# 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
+

.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
+

.vale/styles/config/vocabularies/local/accept.txt

@@ -0,0 +1,3 @@
+nftables
+aproxy
+allowlists

CONTRIBUTING.md

@@ -1,13 +1,11 @@
-<!-- Remember to update this file for your charm -- replace <charm-name> with the appropriate name. -->
-
 # Contributing
 
-This document explains the processes and practices recommended for contributing enhancements to the <charm-name> charm.
+This document explains the processes and practices recommended for contributing enhancements to the aproxy charm.
 
 ## Overview
 
 - Generally, before developing enhancements to this charm, you should consider [opening an issue
-  ](link to issues page) explaining your use case.
+  ](https://github.com/canonical/aproxy-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 Matrix public channel](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
   or [Discourse](https://discourse.charmhub.io/).
@@ -29,10 +27,8 @@ When contributing, you must abide by the
 
 ## Releases and versions
 
-This project uses [semantic versioning](https://semver.org/).
-
 Please ensure that any new feature, fix, or significant change is documented by
-adding an entry to the [CHANGELOG.md](link-to-changelog) file.
+adding an entry to the [CHANGELOG.md](https://github.com/canonical/aproxy-operator/blob/main/docs/changelog.md) file.
 
 To learn more about changelog best practices, visit [Keep a Changelog](https://keepachangelog.com/).
 
@@ -43,7 +39,7 @@ notify in advance the people involved to avoid confusion;
 also, reference the issue or bug number when you submit the changes.
 
 - [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks)
-  our [GitHub repository](link-to-github-repo)
+  our [GitHub repository](https://github.com/canonical/aproxy-operator)
   and add the changes to your fork, properly structuring your commits,
   providing detailed commit messages and signing your commits.
 - Make sure the updated project builds and runs without warnings or errors;
@@ -80,7 +76,7 @@ your pull request must provide the following details:
   - The [contributing guide](https://github.com/canonical/is-charms-contributing-guide) was applied
   - The changes are compliant with [ISD054 - Managing Charm Complexity](https://discourse.charmhub.io/t/specification-isd014-managing-charm-complexity/11619)
   - The documentation is updated
-  - The PR is tagged with appropriate label (trivial, senior-review-required)
+  - The PR is tagged with appropriate label (trivial, senior-review-required, documentation, etc.)
   - The changelog has been updated
 
 ### Signing commits
@@ -91,7 +87,7 @@ we use the [Canonical contributor license agreement](https://assets.ubuntu.com/v
 
 #### Canonical contributor agreement
 
-Canonical welcomes contributions to the <charm-name> charm. Please check out our
+Canonical welcomes contributions to the aproxy charm. Please check out our
 [contributor agreement](https://ubuntu.com/legal/contributors) if you're interested in contributing to the solution.
 
 The CLA sign-off is simple line at the
@@ -111,8 +107,8 @@ To make contributions to this charm, you'll need a working
 
 The code for this charm can be downloaded as follows:
 
-```
-git clone https://github.com/canonical/<charm-name>
+```bash
+git clone https://github.com/canonical/aproxy-operator
 ```
 
 You can create an environment for development with `python3-venv`.
@@ -135,28 +131,9 @@ that can be used for linting and formatting code when you're preparing contribut
 * ``tox -e lint``: Runs a range of static code analysis to check the code.
 * ``tox -e static``: Runs other checks such as ``bandit`` for security issues.
 
-### Build the rock and charm
-
-Use [Rockcraft](https://documentation.ubuntu.com/rockcraft/en/latest/) to create an
-OCI image for the <charm-name> app, and then upload the image to a MicroK8s registry,
-which stores OCI archives so they can be downloaded and deployed.
-
-Enable the MicroK8s registry:
-
-```bash
-microk8s enable registry
-```
-
-The following commands pack the OCI image and push it into
-the MicroK8s registry:
-
-```bash
-cd <project_dir>
-rockcraft pack
-skopeo --insecure-policy copy --dest-tls-verify=false oci-archive:<rock-name>.rock docker://localhost:32000/<app-name>:latest
-```
+### Build the charm
 
-Build the charm in this git repository using:
+Aproxy is a subordinate machine charm that installs a snap and configures nftables. Build the charm in this git repository using:
 
 ```shell
 charmcraft pack
@@ -169,8 +146,10 @@ charmcraft pack
 juju add-model charm-dev
 # Enable DEBUG logging
 juju model-config logging-config="<root>=INFO;unit=DEBUG"
-# Deploy the charm
-juju deploy ./<charm-name>.charm 
+# Deploy the charm with a required config
+juju deploy ./aproxy.charm --config proxy-address=<target.proxy>
+# Integrate with a principal charm
+juju integrate aproxy <principal-charm>
 ```
 
 

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
+

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)
+