docs: update 12-factor tutorials #2085

erinecon · 2025-01-17T15:50:50Z

Update the 12-factor tutorials.

Specific updates:

Convert to reStructuredText
Incorporate feedback from UX session with Daniele
Update all tutorials for consistency (feedback from previous PRs, feedback from Daniele)

lengau · 2025-01-18T02:33:13Z

Hey Erin, I really appreciate this work! Just a note, this is going to conflict with #2083 as it also moves these files to rst. You may want to try to coordinate with @jahn-junior, though I imagine we'll be merging his PR on Monday or Tuesday.

erinecon · 2025-01-20T12:36:15Z

Hey Erin, I really appreciate this work! Just a note, this is going to conflict with #2083 as it also moves these files to rst. You may want to try to coordinate with @jahn-junior, though I imagine we'll be merging his PR on Monday or Tuesday.

Hi @lengau, thanks for letting me know about the other PR. I was under the impression that the 12-factor docs weren't going to be touched since we had planned work to refactor them (See this comment on PR #2010 ). I see there's also #2048 with the how-to guide that I'm planning on refactoring, but that's for a later PR, so I will hold off on that work until after the PR has been merged.

It seems unfortunately that any changes to the Django tutorial might be overwritten by the work in this PR, but I will not touch the FastAPI or Go tutorials until after #2083 has been merged. Thanks again for letting me know.

Fixes canonical#1721 CRAFT-3352

…raft into update-tutorials

lengau · 2025-01-21T16:20:22Z

Hey @erinecon !

On #2048: I'm happy for you to take over that one or to close it unmerged if you want to redo the MD -> rST conversion in your own PR, or we can work together to prioritise the completion so it won't affect you.

Hopefully you should be able to rebase this PR either on #2083 or on main once it's merged and not have too many conflicts.

erinecon · 2025-01-21T17:50:49Z

Hi @lengau , thanks for the offer. I'm fine with waiting for #2048 to be merged before working on a new PR. I appreciate the work you're all doing to convert the files to rST, it saves me a bunch of time! :)

…raft into update-tutorials

lengau · 2025-02-14T19:08:51Z

docs/tutorial/write-your-first-kubernetes-charm-for-a-django-app.rst

Just for convenience: https://canonical-charmcraft--2085.com.readthedocs.build/en/2085/tutorial/write-your-first-kubernetes-charm-for-a-django-app/

lengau · 2025-02-14T19:14:16Z

docs/reuse/tutorial/setup_edge.rst

+.. code-block:: bash
+
+    multipass launch --cpus 4 --disk 50G --memory 4G --name charm-dev 24.04


I just noticed this, which is probably not how you intend it to look:

Changing to:

Suggested change

.. code-block:: bash

multipass launch --cpus 4 --disk 50G --memory 4G --name charm-dev 24.04

.. code-block:: terminal

multipass launch --cpus 4 --disk 50G --memory 4G --name charm-dev 24.04

changes the highlighting (this is from a different branch which is why the text is different):

terminal falls back to no highlighting, as it's not a Pygments lexer:

WARNING: Pygments lexer name 'terminal' is not known

Other tools that use Pygments know how to read it correctly. An example would be VS Code:

I'm blaming our doc stack. If the issue is really bothersome we can set the lexer to text for those odd lines. It's not highlighting much, anyway.

lengau · 2025-02-14T19:16:19Z

docs/tutorial/write-your-first-kubernetes-charm-for-a-fastapi-app.rst

https://canonical-charmcraft--2085.com.readthedocs.build/en/2085/tutorial/write-your-first-kubernetes-charm-for-a-fastapi-app/

lengau · 2025-02-14T19:21:47Z

docs/tutorial/write-your-first-kubernetes-charm-for-a-flask-app.rst

+
+.. note::
+
+   The ``psycopg2-binary`` package is needed so the Flask application can


I understand why the tutorial is this way, but at some point it'd probably be worth documenting uhh... somewhere (no idea where is the right place except that it's definitely out of scope here) how to do the "preferred" method of getting psycopg2 from source and including relevant Ubuntu packages in the rock.

lengau · 2025-02-14T19:22:06Z

docs/tutorial/write-your-first-kubernetes-charm-for-a-flask-app.rst

https://canonical-charmcraft--2085.com.readthedocs.build/en/2085/tutorial/write-your-first-kubernetes-charm-for-a-flask-app/

lengau

Thanks for all this work Erin! Everything else is well beyond me so I'm approving for whatever you and @medubelko do! If one of you will ping me when it's ready to merge I can add it to the queue. I think Michael can too, and if not I should fix that.

medubelko

Lots of little bits to consider for the Django tutorial.

docs/tutorial/write-your-first-kubernetes-charm-for-a-django-app.rst

medubelko · 2025-02-15T00:01:37Z

docs/tutorial/write-your-first-kubernetes-charm-for-a-django-app.rst

-Use that to create a charm with ``charmcraft``. Use that to test-deploy, configure,
-etc., your Django application on a local Kubernetes cloud, ``microk8s``, with
-``juju``. All of that multiple times, mimicking a real development process.
+This tutorial should take 90 minutes for you to complete.


Ouch. :( If they take this long, we should revisit and split them later in another cycle.

Django probably does take closer to 90 min, but the other frameworks probably take closer to 60 minutes with a decently powerful machine and stable internet. The UX research showed that 90 minutes is closer to reality -- and somewhat surprisingly, the research also showed that the majority of users didn't mind the length of any of the tutorials. They appreciated that the tutorial was thorough and stepped through the entire production process.

We can split them and test with users to see whether it harms the UX -- something to consider down the line

medubelko · 2025-02-15T00:04:30Z

docs/tutorial/write-your-first-kubernetes-charm-for-a-django-app.rst

+   If you're new to the charming world: Django applications are
+   specifically supported with a coordinated pair of profiles
+   for an OCI container image (**rock**) and corresponding
+   packaged software (**charm**) that allow for the application
+   to be deployed, integrated and operated on a Kubernetes
+   cluster with the Juju orchestration engine.


In discussion offline.

docs/tutorial/write-your-first-kubernetes-charm-for-a-django-app.rst

medubelko · 2025-02-15T00:05:54Z

docs/tutorial/write-your-first-kubernetes-charm-for-a-django-app.rst


-    A package consisting of YAML files + Python code that will automate every
-    aspect of an application's lifecycle so it can be easily orchestrated with Juju.
+-  A working station, e.g., a laptop, with amd64 or arm64 architecture


amd64

There are several minute microcopy/terminology patterns, some in the style guide and some without, that we'd like to hold Starcraft docs to. Would you mind if I committed them to your branch?

Yes, that's fine with me :)

medubelko · 2025-02-15T01:47:46Z

docs/tutorial/write-your-first-kubernetes-charm-for-a-django-app.rst


-.. code-block:: bash
+.. note::


The text sounds essential, not optional.

medubelko · 2025-02-15T01:49:55Z

docs/tutorial/write-your-first-kubernetes-charm-for-a-django-app.rst

-for example:
+Now you can open a new tab and visit http://django-hello-world. The
+Django app should respond in the browser with
+``The install worked successfully! Congratulations!``.


Block quote?

medubelko · 2025-02-15T01:51:31Z

docs/tutorial/write-your-first-kubernetes-charm-for-a-django-app.rst


-    from django.contrib import admin
-    from django.urls import include, path
+The generated Django application does not come with an app, which is why


application does not come with an app

Potentially confusing...

I agree with you, but AFAIK, this is the terminology used by Django devs. Originally we called this section "Add a root endpoint", but a certain tester said that this would be unknown and confusing to the average Django developer.

medubelko · 2025-02-15T01:58:42Z

docs/tutorial/write-your-first-kubernetes-charm-for-a-django-app.rst

+``django.urls`` to contain ``include`` and the value of ``urlpatterns`` to
+include ``path('', include("greeting.urls")`` like in the following example:


include... to include

A bit difficult to parse. Simplify?

I gave it an attempt, please let me know if you think it's clearer

docs/tutorial/write-your-first-kubernetes-charm-for-a-django-app.rst

evildmp

This looks excellent, thanks for all the work that has gone into creating and reviewing it.

Let's get it merged now and published and improve in the next iteration. I'd like to see it up as soon as possible.

evildmp · 2025-02-19T15:47:03Z

docs/reuse/tutorial/setup_edge.rst

@@ -0,0 +1,93 @@
+First, install Multipass.
+
+.. seealso::


We use blockquotes for these in the rest of the docs.

We should use blockquotes for quoting nlocks of text and nothing else. The Juju CTA examples are incorrect and should be changed. seealso is the correct way to do it.

@tonyandrewmeyer

This PR replaces links to https://juju.is/docs/ by internal cross-references to other Ops pages or intersphinx cross-references to Juju pages (as appropriate). **Not included in this PR** - The link in https://ops.readthedocs.io/en/latest/howto/get-started-with-charm-testing.html#charmcraft-profiles that should point to the Charmcraft docs. I'll follow up with a separate PR after canonical/charmcraft#2085 gets merged into Charmcraft. - Links in the code samples of the Kubernetes tutorial (for example, in [Create a minimal Kubernetes charm](https://ops.readthedocs.io/en/latest/tutorial/from-zero-to-hero-write-your-first-kubernetes-charm/create-a-minimal-kubernetes-charm.html)). I think it would be better to tackle these separately when improving the tutorial - @tonyandrewmeyer what do you think?

erinecon and others added 7 commits January 20, 2025 15:02

docs: remove django md file, add django rst file

2236118

fix: fix lint failures

84f07f9

docs: add django tutorial spread test

04a4817

fix: remove trailing spaces

1e9b7b6

fix: remove trailing spaces

da47d6b

fix(store): better error message with fetch-lib (canonical#2084)

5286e23

Fixes canonical#1721 CRAFT-3352

build(deps): update bugfixes

dc917b1

erinecon force-pushed the update-tutorials branch from da4cfba to dc917b1 Compare January 20, 2025 20:03

erinecon added 5 commits January 20, 2025 15:04

Merge branch 'main' into update-tutorials

65462a4

docs: remove experimental extension flag

7669dea

Merge branch 'update-tutorials' of https://github.com/erinecon/charmc…

ae603d9

…raft into update-tutorials

docs: add reuse setup file

f3fd4b7

docs: replace code with wrapped commands

92ac018

fix: remove duplicate content, break commands up

659b28d

erinecon changed the title ~~update 12-factor tutorials~~ docs: update 12-factor tutorials Jan 21, 2025

erinecon added 11 commits January 22, 2025 08:44

Merge branch 'main' into update-tutorials

69eb47d

fix: incorporate changes from Design team

d28c88e

Merge branch 'main' into update-tutorials

fd27611

fix: revert command to run app locally

5514ed9

Merge branch 'update-tutorials' of https://github.com/erinecon/charmc…

ae67ad0

…raft into update-tutorials

fix: update Django spread test

4b4a684

Merge branch 'main' into update-tutorials

ac11344

docs: update Django pack warning

9046167

docs: update Django charm pack warning

bdc53c2

fix: update Flask task file

ecd8773

docs: update Flask tutorial files

2991bf5

erinecon added 4 commits February 13, 2025 15:44

fix(docs): update setup_stable warning

16e4f63

fix(docs): update code-blocks to code

5fba1c8

docs: add rockcraft/charmcraft clean

0569d89

fix: trailing whitespace

0f6abc6

This was referenced Feb 14, 2025

docs: fix links that pointed to earlier Juju docs canonical/operator#1575

Merged

docs: update links to Charmcraft docs canonical/operator#1582

Merged

erinecon added 3 commits February 14, 2025 07:48

fix(docs): incorporate UX review

2011d87

test(docs): spread test debug

1553ccb

test(docs): remove debug line

1b73278

lengau self-requested a review February 14, 2025 18:51

lengau reviewed Feb 14, 2025

View reviewed changes

lengau approved these changes Feb 14, 2025

View reviewed changes

erinecon and others added 3 commits February 14, 2025 16:20

docs: add microk8s status output explanation

0e3bf13

test(docs): debugging spread tests

50b2991

fix: tutorial build errors

4849205

medubelko approved these changes Feb 15, 2025

View reviewed changes

erinecon added 5 commits February 18, 2025 14:32

Merge branch 'main' into update-tutorials

7d71b0a

fix(docs): incorporate TA review

10db7a9

fix(docs): update setup_edge.rst

1570aff

fix(docs): incorporate review for django

e024943

fix(docs): trailing whitespace

365395d

evildmp approved these changes Feb 19, 2025

View reviewed changes

lengau merged commit 79fa5ad into canonical:main Feb 19, 2025
30 of 31 checks passed

erinecon deleted the update-tutorials branch February 19, 2025 23:53

erinecon restored the update-tutorials branch February 24, 2025 19:40

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: update 12-factor tutorials #2085

docs: update 12-factor tutorials #2085

erinecon commented Jan 17, 2025

lengau commented Jan 18, 2025

erinecon commented Jan 20, 2025

lengau commented Jan 21, 2025

erinecon commented Jan 21, 2025

lengau Feb 14, 2025

lengau Feb 14, 2025

medubelko Feb 14, 2025 •

edited

Loading

lengau Feb 14, 2025

lengau Feb 14, 2025

lengau Feb 14, 2025

lengau left a comment

medubelko left a comment

medubelko Feb 15, 2025

erinecon Feb 18, 2025

medubelko Feb 15, 2025

medubelko Feb 15, 2025

erinecon Feb 18, 2025

medubelko Feb 15, 2025

medubelko Feb 15, 2025

medubelko Feb 15, 2025

erinecon Feb 18, 2025

medubelko Feb 15, 2025

erinecon Feb 18, 2025

evildmp left a comment

evildmp Feb 19, 2025

		.. code-block:: bash

		multipass launch --cpus 4 --disk 50G --memory 4G --name charm-dev 24.04


		.. note::

		The ``psycopg2-binary`` package is needed so the Flask application can

		``django.urls`` to contain ``include`` and the value of ``urlpatterns`` to
		include ``path('', include("greeting.urls")`` like in the following example:

docs: update 12-factor tutorials #2085

docs: update 12-factor tutorials #2085

Conversation

erinecon commented Jan 17, 2025

lengau commented Jan 18, 2025

erinecon commented Jan 20, 2025

lengau commented Jan 21, 2025

erinecon commented Jan 21, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

medubelko Feb 14, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lengau left a comment

Choose a reason for hiding this comment

medubelko left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

evildmp left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

medubelko Feb 14, 2025 •

edited

Loading