From a76b88586736ed43252f3533c56ce9900e3b4f3e Mon Sep 17 00:00:00 2001 From: arturo-seijas Date: Thu, 4 Jan 2024 09:51:05 +0100 Subject: [PATCH 1/6] Add pull request teamplate --- .github/pull_request_template.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..5ce31d9 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,32 @@ +Applicable spec: + +### Overview + + + +### Rationale + + + +### Juju Events Changes + + + +### Module Changes + + + +### Library Changes + + + +### Checklist + +- [ ] The [charm style guide](https://juju.is/docs/sdk/styleguide) was applied +- [ ] 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 generated using `src-docs` +- [ ] The documentation for charmhub is updated +- [ ] The PR is tagged with appropriate label (`urgent`, `trivial`, `complex`) + + From 01d5d2abcfaa71c5894253e8a66089c0792fa15b Mon Sep 17 00:00:00 2001 From: arturo-seijas Date: Thu, 4 Jan 2024 10:00:30 +0100 Subject: [PATCH 2/6] Add src docs --- generate-src-docs.sh | 6 +++ requirements.txt | 1 + src-docs/charm.py.md | 98 ++++++++++++++++++++++++++++++++++++++ src-docs/file_reader.py.md | 32 +++++++++++++ tox.ini | 14 ++++++ 5 files changed, 151 insertions(+) create mode 100644 generate-src-docs.sh create mode 100644 src-docs/charm.py.md create mode 100644 src-docs/file_reader.py.md diff --git a/generate-src-docs.sh b/generate-src-docs.sh new file mode 100644 index 0000000..2e6195c --- /dev/null +++ b/generate-src-docs.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash + +# Copyright 2023 Canonical Ltd. +# See LICENSE file for licensing details. + +lazydocs --no-watermark --output-path src-docs src/* diff --git a/requirements.txt b/requirements.txt index 408016c..9684eab 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,2 +1,3 @@ +cosl ops>=1.2.0 tabulate diff --git a/src-docs/charm.py.md b/src-docs/charm.py.md new file mode 100644 index 0000000..e7cac91 --- /dev/null +++ b/src-docs/charm.py.md @@ -0,0 +1,98 @@ + + + + +# module `charm.py` +Charm for Content-cache on Kubernetes. + +**Global Variables** +--------------- +- **REQUIRED_INGRESS_RELATION_FIELDS** +- **CACHE_PATH** +- **CONTAINER_NAME** +- **EXPORTER_CONTAINER_NAME** +- **CONTAINER_PORT** +- **REQUIRED_JUJU_CONFIGS** + + +--- + +## class `ContentCacheCharm` +Charm the service. + +Attrs: on: Ingress Charm Events ERROR_LOG_PATH: NGINX error log ACCESS_LOG_PATH: NGINX access log _metrics_endpoint: Provider of metrics for Prometheus charm _logging: Requirer of logs for Loki charm _grafana_dashboards: Dashboard Provider for Grafana charm ingress_proxy_provides: Ingress proxy provider ingress: Ingress requirer unit: Charm's designated juju unit model: Charm's designated juju model + + + +### function `__init__` + +```python +__init__(*args) +``` + +Init function for the charm. + + + +**Args:** + + - `args`: Variable list of positional arguments passed to the parent constructor. + + +--- + +#### property app + +Application that this unit is part of. + +--- + +#### property charm_dir + +Root directory of the charm as it is running. + +--- + +#### property config + +A mapping containing the charm's config and current values. + +--- + +#### property meta + +Metadata of this charm. + +--- + +#### property model + +Shortcut for more simple access the model. + +--- + +#### property unit + +Unit that this execution is responsible for. + + + +--- + + + +### function `configure_workload_container` + +```python +configure_workload_container(event: ConfigChangedEvent) → None +``` + +Configure/set up workload container inside pod. + + + +**Args:** + + - `event`: config-changed event. + + diff --git a/src-docs/file_reader.py.md b/src-docs/file_reader.py.md new file mode 100644 index 0000000..87566b9 --- /dev/null +++ b/src-docs/file_reader.py.md @@ -0,0 +1,32 @@ + + + + +# module `file_reader.py` +Short module for file reverse reading. + + +--- + + + +## function `readlines_reverse` + +```python +readlines_reverse(qfile) → Generator[int, NoneType, NoneType] +``` + +Read the lines of a file in reverse order in a lazy way. + + + +**Args:** + + - `qfile`: File in StringIO format. + + + +**Yields:** + A row from the read file. + + diff --git a/tox.ini b/tox.ini index bb5d90c..7c23669 100644 --- a/tox.ini +++ b/tox.ini @@ -72,6 +72,20 @@ commands = -m pytest --ignore={[vars]tst_path}integration -v --tb native -s {posargs} coverage report +[testenv:src-docs] +allowlist_externals=sh +setenv = + PYTHONPATH = {toxinidir}:{toxinidir}/lib:{[vars]src_path} +description = Generate documentation for src +deps = + cosl + jinja2 + lazydocs + -r{toxinidir}/requirements.txt +commands = + ; can't run lazydocs directly due to needing to run it on src/* which produces an invocation error in tox + sh generate-src-docs.sh + [testenv:coverage-report] description = Create test coverage report deps = From 1e1604e78603171a71cd008113e5c665b890e473 Mon Sep 17 00:00:00 2001 From: arturo-seijas Date: Thu, 4 Jan 2024 10:01:48 +0100 Subject: [PATCH 3/6] update contributing docs --- docs/how-to/contribute.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/how-to/contribute.md b/docs/how-to/contribute.md index 31861d2..79e0196 100644 --- a/docs/how-to/contribute.md +++ b/docs/how-to/contribute.md @@ -56,6 +56,15 @@ Note that the [content-cache-image](content-cache.Dockerfile) image needs to be * `tox -e integration`: Runs the integration tests. +### Generating src docs for every commit + +Run the following command: + +```bash +echo -e "tox -e src-docs\ngit add src-docs\n" >> .git/hooks/pre-commit +chmod +x .git/hooks/pre-commit +``` + ## Build charm Build the charm in this git repository using: From 59a5974a475326913d27d07e050d39eb5066a0e9 Mon Sep 17 00:00:00 2001 From: arturo-seijas <102022572+arturo-seijas@users.noreply.github.com> Date: Thu, 4 Jan 2024 10:34:49 +0100 Subject: [PATCH 4/6] Update generate-src-docs.sh Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- generate-src-docs.sh | 3 +++ 1 file changed, 3 insertions(+) diff --git a/generate-src-docs.sh b/generate-src-docs.sh index 2e6195c..77f013b 100644 --- a/generate-src-docs.sh +++ b/generate-src-docs.sh @@ -1,3 +1,6 @@ +# Copyright 2024 Canonical Ltd. +# See LICENSE file for licensing details. + #!/usr/bin/env bash # Copyright 2023 Canonical Ltd. From dfd47d5f352a91dab3b905b0e542d7e0cb1f94d7 Mon Sep 17 00:00:00 2001 From: arturo-seijas Date: Thu, 4 Jan 2024 10:35:53 +0100 Subject: [PATCH 5/6] fix copyright header --- generate-src-docs.sh | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/generate-src-docs.sh b/generate-src-docs.sh index 77f013b..d13066a 100644 --- a/generate-src-docs.sh +++ b/generate-src-docs.sh @@ -1,9 +1,6 @@ -# Copyright 2024 Canonical Ltd. -# See LICENSE file for licensing details. - #!/usr/bin/env bash -# Copyright 2023 Canonical Ltd. +# Copyright 2024 Canonical Ltd. # See LICENSE file for licensing details. lazydocs --no-watermark --output-path src-docs src/* From 6835700e4b7ba902b115203942e32a010d3770e5 Mon Sep 17 00:00:00 2001 From: arturo-seijas Date: Thu, 4 Jan 2024 10:50:06 +0100 Subject: [PATCH 6/6] remove unused dep --- tox.ini | 1 - 1 file changed, 1 deletion(-) diff --git a/tox.ini b/tox.ini index 9941724..a379122 100644 --- a/tox.ini +++ b/tox.ini @@ -79,7 +79,6 @@ setenv = description = Generate documentation for src deps = cosl - jinja2 lazydocs -r{toxinidir}/requirements.txt commands =