Docs - Githubissues

jdkandersson commented 7 months ago

Applicable spec: N/A

Overview

Adds key documentation

Rationale

So that people know how to use PaaS App Charmer

Juju Events Changes

Module Changes

Library Changes

Checklist

[x] The charm style guide was applied
[x] The contributing guide was applied
[x] The changes are compliant with ISD054 - Managing Charm Complexity
[x] The documentation is generated using src-docs
[x] The documentation for charmhub is updated
[x] The PR is tagged with appropriate label (urgent, trivial, complex)

jdkandersson commented 6 months ago

This PR contains material designed to

introduce the PaaS app charmer product;

document individual PaaS app charmer suites (can we call them that? I mean the Rockcraft + Charmcraft profile+extension for each supported framework)

document how to contribute to this project.

I think 1 and 3 can stay in the GH repo (just that I'd combine the README and the Overview into a more focused README).

Bits of 1 and 2 can go into the charm SDK docs. Regarding this:

While the way you grouped content here suggests all of How-to guides, Reference, and Explanation, I think we'd be better off if we conveyed all the relevant bits in the form of a single Reference with the title "PaaS app charmer" introducing the product, commenting on the general structure of each suite (again, can we call the package for a particular framework a "suite"?) (that is, Rockcraft profile+extension + matching Charmcraft profile+extension that produces files that, among others, use the paas-app-charmer library), and then documenting the particularities of each suite (e.g., part definition meaning and defaults, predefined actions, how configs = envvars, predefined integrations to choose from). I think that would not just scale better but it would also help the user understand the general logic -- when they're using paas-app-charmer they're always at most just editing yaml, where the yaml schemas are really always fundamentally the same and part of the more general workflow of a charmer).

In the tutorial we should link to the Reference. That should help people move from the tutorial to mastering their Paas app charmer suites more generally.

In the Reference we should link pervasively to the upstream (Rockcraft, *craft parts, Juju) wherever possible. That will help the user move from the Paas app charmer to the charming world more generally. (E.g., they should understand that a config or a part or what they see in their charm.py are not just quirks of the PaaS app charmer -- they're general concepts that they can build upon to master charming and Juju more generally.

I've started making moves in this direction in the docs but am unfortunately not yet done. I'll keep you posted.

I think this makes sense

github-actions[bot] commented 2 months ago

Test coverage for e0186eb04c25610e57c3aa130096775090c0d564

Name                                            Stmts   Miss Branch BrPart  Cover   Missing
-------------------------------------------------------------------------------------------
paas_app_charmer/__init__.py                       29     14      0      0    52%   13-14, 19-20, 26-27, 33-34, 40-41, 47-48, 54-55
paas_app_charmer/_gunicorn/__init__.py              0      0      0      0   100%
paas_app_charmer/_gunicorn/charm.py                15      0      0      0   100%
paas_app_charmer/_gunicorn/webserver.py            76      4     14      1    94%   162, 174-180
paas_app_charmer/_gunicorn/workload_config.py       8      0      0      0   100%
paas_app_charmer/_gunicorn/wsgi_app.py             18      0      0      0   100%
paas_app_charmer/app.py                           120      0     48      2    99%   94->exit, 135->141
paas_app_charmer/charm.py                         212     25     46      4    88%   32-33, 40-41, 190-191, 193-194, 215->exit, 227-231, 284-286, 339-340, 345, 350, 355, 365, 370, 375, 380, 385, 410
paas_app_charmer/charm_state.py                   107      2     20      2    97%   184, 268
paas_app_charmer/charm_utils.py                    23      0      0      0   100%
paas_app_charmer/database_migration.py             35      0      2      0   100%
paas_app_charmer/databases.py                      25      2     11      1    92%   89-90
paas_app_charmer/django/__init__.py                 2      0      0      0   100%
paas_app_charmer/django/charm.py                   34      4      6      2    85%   44, 81, 96-97
paas_app_charmer/exceptions.py                      5      0      0      0   100%
paas_app_charmer/flask/__init__.py                  2      0      0      0   100%
paas_app_charmer/flask/charm.py                    24      0      0      0   100%
paas_app_charmer/observability.py                  16      0      4      1    95%   40->44
paas_app_charmer/secret_storage.py                 50      3     16      5    88%   51, 55->54, 56->58, 86, 105
paas_app_charmer/utils.py                          11      2     12      2    65%   29, 31
-------------------------------------------------------------------------------------------
TOTAL                                             812     56    179     20    92%

Static code analysis report

Run started:2024-08-21 04:55:17.895200

Test results:
    No issues identified.

Code scanned:
    Total lines of code: 1760
    Total lines skipped (#nosec): 0
    Total potential issues skipped due to specifically being disabled (e.g., #nosec BXXX): 0

Run metrics:
    Total issues (by severity):
        Undefined: 0
        Low: 0
        Medium: 0
        High: 0
    Total issues (by confidence):
        Undefined: 0
        Low: 0
        Medium: 0
        High: 0
Files skipped (0):

canonical / paas-app-charmer