docs: add "How to manage 12-factor app charms" #2048
Conversation
lengau
force-pushed
the
docs/CRAFT-3819/12-factor
branch
2 times, most recently
from
2055c2a to
b21a0b7
Compare
I'm breaking down the content from PR #2010 into smaller chunks. This is "How to manage 12-factor app charms" converted to RST: https://github.com/canonical/charmcraft/blob/737976c943a601adccd883ffa6a276bce625c9a1/docs/howto/manage-12-factor-app-charms.md The main differences from the Markdown version: - Uses tabs instead of dropdowns (matching the Rockcraft docs: https://documentation.ubuntu.com/rockcraft/en/latest/how-to/build-a-12-factor-app-rock/) - "See also" blocks are added as cards
lengau
force-pushed
the
docs/CRAFT-3819/12-factor
branch
from
b21a0b7 to
529446b
Compare
| .. raw:: html | ||
|
|
||
| <!--TODO: There are a few more low-hanging fruit topics that we can and should cover: | ||
|
|
||
| When we create such sections we should include thinks at both the rock and the charm level (because the 12-Factor app app charm wants you to think about them in this coupled fashion). However, for the Rockcraft things, we should have those sections point to Rockcraft docs. For example: | ||
|
|
||
| ## Update the OCI image for a 12-Factor app charm | ||
|
|
||
| See {ref}`Rockcraft Documentation > How to update the OCI image... <15018md>` | ||
|
|
||
| --> |
There was a problem hiding this comment.
I think we could use Sphinx comments to comment out the whole block.
I like that you've left it as Markdown, so we know it's not finished.
There was a problem hiding this comment.
It's not just left as Markdown, it's left as the raw pandoc output 🙂
| .. card:: See also | ||
| :link: https://juju.is/docs/juju/charmed-operator | ||
|
|
||
| ``juju`` | 12-factor app charms |
There was a problem hiding this comment.
I'm not jazzed by using cards, for several reasons. I think we can make do by making this a note or a plain paragraph, which is closer to the original structure (blockquote). That way we won't need to introduce new patterns and directives.
Longer-term I'd like to come up with smoother wording for introducing these links. Dressing them up as notes will be a good way to encourage me to correct them, since you know I don't like notes. :)
There was a problem hiding this comment.
I revisited this question with Dora. Let's instead use block quotes (two prepended spaces) for these.
That's also a structure we don't use often, so I'll easily be able to pick it up in later reviews/rewrites.
| environment variables, for example, to pass a token for a service. Add | ||
| the configuration in ``charmcraft.yaml``: | ||
|
|
||
| .. code:: text |
There was a problem hiding this comment.
Any reason not to use yaml?
There was a problem hiding this comment.
Just missed this one in the pandoc output.
| .. code:: text | |
| .. code:: yaml |
| The configuration can be set on the deployed charm using | ||
| ``juju config <app name> token=<token>``. | ||
|
|
||
| .. card-carousel:: 2 |
There was a problem hiding this comment.
Oof, I'm very strongly not in favour of how this looks, either.
| you may use to configure your 12-factor application. | ||
|
|
||
| For example, if you wish to integrate your 12-factor application with | ||
| PostgreSQL (`machine <https://charmhub.io/postgresql>`__ or |
There was a problem hiding this comment.
It looks like Pandoc added extra underscores to links.
| creates the following environment variables you may use to configure | ||
| your 12-factor application: | ||
|
|
||
| - ``POSTGRESQL_DB_CONNECT_STRING`` |
There was a problem hiding this comment.
It also looks like it added two spaces after list iterators.
|
|
||
| Once the charm is deployed, you can add a Juju secret to the model:: | ||
|
|
||
| juju add-secret my-api-token value=1234 othervalue=5678 |
There was a problem hiding this comment.
There's no rule about this, but for consistency I think it would be better to use the code directive for blocks, unless it's code imported from a literalinclude.
| .. tabs:: | ||
| :sync-group: framework | ||
|
|
||
| .. group-tab:: Flask | ||
|
|
||
| .. group-tab:: Django | ||
|
|
||
| Use the ``create-superuser`` action to create a new Django admin account:: | ||
|
|
||
| juju run <app name> create-superuser username=<username> email=<email> | ||
|
|
||
| You must provide the username and email address. | ||
|
|
||
| .. group-tab:: FastAPI | ||
|
|
||
| .. group-tab:: Go |
There was a problem hiding this comment.
The solution to the empty tags is to modify both the content and structure. If this action only applies to Django, then let's either:
- include "Django" in the heading, or
- Start the section with a paragraph that states Django is the only framework with this capability.
I'm breaking down the content from PR #2010 into smaller chunks.
This is "How to manage 12-factor app charms" converted to RST: https://github.com/canonical/charmcraft/blob/737976c943a601adccd883ffa6a276bce625c9a1/docs/howto/manage-12-factor-app-charms.md
The main differences from the Markdown version:
Rendered link: https://canonical-charmcraft--2048.com.readthedocs.build/en/2048/howto/manage-12-factor-app-charms/
CRAFT-3819