Skip to content

Commit a1a3d4b

Browse files
tmihocerineconmedubelkolengau
authored
docs: add, refactor, and reformat discourse docs feat. charmcraft (canonical#2010)
This PR adds all the juju.is/docs content featuring Charmcraft. The content was originally formatted for Discourse; this PR reformats it to serve the RTD project the docs are destined for. The content was also originally entangled with Ops content; this PR significantly refactors -- as well as clarifies and tries to complete -- everything to serve the stand-alone Charmcraft docs set it is destined for. Issues that should be fixed in subsequent PRs: - Everywhere: (1) (a) Links to juju.is will work, as even after moving docs out of there we'll have redirects; however, they should be updated. (b) Links to ops docs are empty -- they reference content I'm planning to move there post-refactoring; once we have them in place, which should be in the next few days and pre-official-Charmcraft-RTD-launch, we should add them in Charmcraft docs. - Tutorial: The tutorial should also be offered in the "regular" flavor, that is, for apps that are not 12-factor. That flavor should also feature the publish step. (See, e.g., our old Kubernetes tutorial, which includes https://juju.is/docs/sdk/publish-your-charm-on-charmhub . PS If the Charmcraft tutorial starts featuring this, as it should, the old Kubernetes tutorial, which will be moved to the stand-alone Ops docs, can focus on just development, which is what Ops is really all about.) - How-to guides: While this PR surfaces a lot more of Charmcraft and arguably a lot more clearly, there are still corners with cobwebs or gaps. These include: (1) Manage charms (12-factor app) -- I think this doc should be incorporated into the main Manage charms doc, which could have tabs for "regular', "django", etc. (This would align with plans for the juju.is/docs entrypoint into the "federated docs"). (2) The Manage parts doc, which is full of "TBA" -- i.e., has gaps. (3) The docs in "Misc", which are not well integrated with everything else here. (4) Maybe the Manage bundles doc, which doesn't by far tell the full story; given that we're phasing bundles out, it's also perhaps fine not to worry about this too much. (5) Commands `analyse` and `test` are not featured in any how-to guide. - Reference: (1) The autogenerated `charmcraft` CLI command reference docs should have anchors on the template `command-charmcraft-x` and titles on the template "Command `charmcraft x`. This will not better align with existing practices in the Juju world but also results in more clarity when linking to the page using `{ref}`...`` (2) The various file reference docs should be as much as possible autogenerated from source (likely the source will have to be updated first) -- at the very least, file `charmcraft.yaml`. They may also need further clean-up. (3) The part docs are a bit of a mess. We should move any relevant content to the part docs, then link up to that and only keep in Charmcraft the material specific to Charmcraft docs, and then revisit that material as well to streamline it as much as possible (e.g., currently the dump plugin is documented in 3 places). (4) Charmcraft analyzers and linters -- this gives details on pack and analyse but it's not clear in what way it's useful to the reader, so we need to rethink. - Explanation: We have nothing there. I didn't delete that section as I think there is potentially a topic we could have there -- e.g., Charmcraft in the bigger context of Starcraft (a clarification of the general design philosophy there and trends, maybe). PS Some docs may have a Contributors list on the bottom, listing the Discourse handles of the contributors to date. We'll want to rethink how we do that. --------- Co-authored-by: Erin Conley <[email protected]> Co-authored-by: Michael DuBelko <[email protected]> Co-authored-by: Alex Lowe <[email protected]> Co-authored-by: Michael DuBelko <[email protected]>
1 parent 7348ef5 commit a1a3d4b

File tree

71 files changed

+9776
-129
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

71 files changed

+9776
-129
lines changed

‎.editorconfig

+4-1
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,13 @@ tab_width = 2
2727
indent_size = 2
2828
max_line_length = off
2929

30-
[{*.markdown,*.md,*.rst}]
30+
[{*.markdown,*.md}]
3131
max_line_length = off
3232
ij_visual_guides = none
3333

34+
[{*.rst}]
35+
max_line_length = 88
36+
3437
[{*.toml,Cargo.lock,Cargo.toml.orig,Gopkg.lock,Pipfile,poetry.lock}]
3538
max_line_length = off
3639

‎.gitignore

+4-3
Original file line numberDiff line numberDiff line change
@@ -72,9 +72,10 @@ instance/
7272
# Sphinx documentation
7373
docs/_build/
7474
# Auto-generated command reference
75-
/docs/reference/commands/
76-
/docs/reference/_autosummary/
77-
/docs/common/craft-parts
75+
docs/reference/commands/
76+
!docs/reference/commands/index.rst
77+
docs/reference/_autosummary/
78+
docs/common/craft-parts
7879

7980
# PyBuilder
8081
target/

‎common.mk

+1-1
Original file line numberDiff line numberDiff line change
@@ -194,7 +194,7 @@ docs: ## Build documentation
194194

195195
.PHONY: docs-auto
196196
docs-auto: ## Build and host docs with sphinx-autobuild
197-
uv run --extra docs sphinx-autobuild -b html --open-browser --port=8080 --ignore *.kate-swp --ignore docs/reference/commands/** --watch $(PROJECT) $(DOCS) $(DOCS)/_build
197+
uv run --extra docs sphinx-autobuild -b html --open-browser --port=8080 --ignore *.kate-swp --ignore docs/reference/commands/ --watch $(PROJECT) $(DOCS) $(DOCS)/_build
198198

199199
.PHONY: pack-pip
200200
pack-pip: ##- Build packages for pip (sdist, wheel)

‎docs/conf.py

+11
Original file line numberDiff line numberDiff line change
@@ -88,11 +88,13 @@
8888
# documents (so they generate "duplicate label" errors) or they aren't
8989
# used in this documentation at all (so they generate "unreferenced"
9090
# errors).
91+
"explanation/index.rst",
9192
"common/craft-parts/explanation/lifecycle.rst",
9293
"common/craft-parts/explanation/overlay_parameters.rst",
9394
"common/craft-parts/explanation/overlays.rst",
9495
"common/craft-parts/explanation/parts.rst",
9596
"common/craft-parts/explanation/how_parts_are_built.rst",
97+
"common/craft-parts/explanation/dump_plugin.rst",
9698
"common/craft-parts/explanation/overlay_step.rst",
9799
"common/craft-parts/how-to/craftctl.rst",
98100
"common/craft-parts/how-to/include_files.rst",
@@ -113,13 +115,21 @@
113115
"common/craft-parts/reference/plugins/qmake_plugin.rst",
114116
"common/craft-parts/reference/plugins/rust_plugin.rst",
115117
"common/craft-parts/reference/plugins/scons_plugin.rst",
118+
"common/craft-parts/reference/plugins/go_plugin.rst",
119+
"common/craft-parts/reference/plugins/go_use_plugin.rst",
120+
"common/craft-parts/reference/plugins/uv_plugin.rst",
116121
# Extra non-craft-parts exclusions can be added after this comment
117122
]
118123

119124
rst_epilog = """
120125
.. include:: /reuse/links.txt
121126
"""
122127

128+
# MyST-specific settings
129+
130+
suppress_warnings = ["myst.domains"] # Suppresses false warnings about missing methods
131+
myst_heading_anchors = 4 # Autogenerates anchors for MD headings
132+
123133
autodoc_default_options = {"exclude-members": "model_post_init"}
124134

125135
# region Options for extensions
@@ -129,6 +139,7 @@
129139
intersphinx_mapping = {
130140
"python": ("https://docs.python.org/3", None),
131141
"craft-parts": ("https://canonical-craft-parts.readthedocs-hosted.com/en/latest/", None),
142+
"ops": ("https://ops.readthedocs.io/en/latest/", None),
132143
"rockcraft": ("https://documentation.ubuntu.com/rockcraft/en/stable/", None),
133144
}
134145
# See also:

‎docs/explanation/index.rst

+2-14
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,6 @@
11
.. _explanation:
22

33
Explanation
4-
***********
4+
===========
55

6-
As Charmcraft is a part of the `Juju Charm SDK <https://juju.is/docs/sdk>`_, most
7-
explanation is hosted on the `Charm SDK docs <https://juju.is/docs/sdk/explanation>`_.
8-
9-
.. toctree::
10-
:maxdepth: 1
11-
12-
/common/craft-parts/explanation/dump_plugin
13-
/common/craft-parts/explanation/filesets
14-
lifecycle
15-
16-
17-
`Charm SDK docs <https://juju.is/docs/sdk/explanation>`_
18-
========================================================
6+
.. toctree

‎docs/howto/build-guides/index.rst

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
.. _howto-build-guides:
2+
3+
Build guides
4+
============
5+
6+
.. toctree::
7+
:maxdepth: 2
8+
9+
Cache intermediate build artefacts <shared-cache>
10+
Pack a hook-based charm with Charmcraft <pack-a-hooks-based-charm-with-charmcraft>
11+
Pack a reactive charm with Charmcraft <pack-a-reactive-charm-with-charmcraft>

‎docs/howto/build-guides/pack-a-hooks-based-charm-with-charmcraft.rst

+120
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
.. _pack-a-hooks-based-charm-with-charmcraft:
2+
3+
How to pack a hooks-based charm with Charmcraft
4+
===============================================
5+
6+
Introduced in Charmcraft 1.4
7+
8+
See first: :external+ops:ref:`turn-a-hooks-based-charm-into-an-ops-charm`
9+
10+
Suppose you have a legacy hooks-only charm, for example, `tiny-bash
11+
<https://github.com/erik78se/tiny-bash>`_, which you can clone with:
12+
13+
.. code-block:: bash
14+
15+
git clone https://github.com/erik78se/tiny-bash
16+
17+
To make it packable by Charmcraft, all you need to do is navigate inside the charm
18+
directory and create a ``charmcraft.yaml`` file with the part definition for a
19+
hooks-based charm, as shown below:
20+
21+
.. code-block:: yaml
22+
23+
type: charm
24+
25+
bases:
26+
- build-on:
27+
- name: "ubuntu"
28+
channel: "20.04"
29+
run-on:
30+
- name: "ubuntu"
31+
channel: "20.04"
32+
33+
parts:
34+
tiny-bash:
35+
plugin: dump
36+
source: .
37+
prime:
38+
- LICENSE
39+
- README.md
40+
- config.yaml
41+
- copyright
42+
- hooks
43+
- icon.svg
44+
- metadata.yaml
45+
46+
After this, you can pack your charm with ``charmcraft pack``, as usual:
47+
48+
.. code-block:: bash
49+
50+
charmcraft pack
51+
52+
If successful, the result should look like the following.
53+
54+
.. terminal::
55+
56+
Charms packed:
57+
tiny-bash_ubuntu-20.04-amd64.charm
58+
59+
The charm file should contain all the files listed in the ``prime`` section of the
60+
``tiny-bash`` part and the charm manifest.
61+
62+
.. code-block:: bash
63+
64+
unzip -l tiny-bash_ubuntu-20.04-amd64.charm
65+
66+
.. terminal::
67+
68+
Archive: tiny-bash_ubuntu-20.04-amd64.charm
69+
Length Date Time Name
70+
--------- ---------- ----- ----
71+
423 2021-11-12 19:37 metadata.yaml
72+
431 2021-11-12 19:37 README.md
73+
12 2021-11-12 19:37 config.yaml
74+
3693 2021-11-12 19:37 icon.svg
75+
38 2021-11-12 19:37 copyright
76+
261 2021-11-12 20:08 manifest.yaml
77+
34523 2021-11-12 19:37 LICENSE
78+
381 2021-11-12 19:37 hooks/update-status
79+
346 2021-11-12 19:37 hooks/start
80+
1294 2021-11-12 19:37 hooks/shared-fs-relation-changed
81+
563 2021-11-12 19:37 hooks/stop
82+
497 2021-11-12 19:37 hooks/leader-elected
83+
447 2021-11-12 19:37 hooks/install
84+
417 2021-11-12 19:37 hooks/leader-settings-changed
85+
811 2021-11-12 19:37 hooks/upgrade-charm
86+
625 2021-11-12 19:37 hooks/config-changed
87+
--------- -------
88+
44762 16 files
89+
90+
And you can also deploy your application with ``juju deploy``, as usual:
91+
92+
.. code-block:: bash
93+
94+
juju deploy ./tiny-bash_ubuntu-20.04-amd64.charm
95+
96+
.. terminal::
97+
98+
Located local charm "tiny-bash", revision 0
99+
Deploying "tiny-bash" from local charm "tiny-bash", revision 0
100+
101+
If successful, the result should look as below, i.e., with the application status
102+
active.
103+
104+
.. code-block:: bash
105+
106+
juju status
107+
108+
.. terminal::
109+
110+
Model Controller Cloud/Region Version SLA Timestamp
111+
default localhost-localhost localhost/localhost 2.9.12 unsupported 17:23:23-03:00
112+
113+
App Version Status Scale Charm Store Channel Rev OS Message
114+
tiny-bash active 1 tiny-bash local 0 ubuntu update-status ran: 20:22
115+
116+
Unit Workload Agent Machine Public address Ports Message
117+
tiny-bash/0* active idle 0 10.2.17.31 update-status ran: 20:22
118+
119+
Machine State DNS Inst id Series AZ Message
120+
0 started 10.2.17.31 juju-55481c-0 focal Running

‎docs/howto/build-guides/pack-a-reactive-charm-with-charmcraft.rst

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
.. _pack-a-reactive-charm-with-charmcraft:
2+
3+
How to pack a reactive charm with Charmcraft
4+
==================================================
5+
6+
Introduced in Charmcraft 1.4.
7+
8+
9+
.. See also: -
10+
.. {ref}\ ``How to set up a charm project <how-to-set-up-a-charm-project>``
11+
.. -
12+
.. {ref}\ ``How to pack your charm using Charmcraft <how-to-pack-a-charm>``
13+
.. - {ref}\ ``About charm types, by creation type <charm-taxonomy>``
14+
15+
To pack a legacy reactive charm with Charmcraft, in the charm directory create a
16+
``charmcraft.yaml`` file with the part definition for a reactive-based charm:
17+
18+
.. code-block:: yaml
19+
20+
type: "charm"
21+
bases:
22+
- build-on:
23+
- name: "ubuntu"
24+
channel: "20.04"
25+
run-on:
26+
- name: "ubuntu"
27+
channel: "20.04"
28+
parts:
29+
charm:
30+
source: .
31+
plugin: reactive
32+
build-snaps: [charm]
33+
34+
Done. Now you can go ahead and pack your reactive-based charm with Charmcraft
35+
in the usual way using ``charmcraft pack``.

‎docs/howto/shared-cache.rst renamed to ‎docs/howto/build-guides/shared-cache.rst

File renamed without changes.

‎docs/howto/index.rst

+19-6
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,25 @@
1-
.. _howto:
1+
.. _how-to-guides:
22

3-
How-To
4-
******
3+
How-to guides
4+
=============
55

66
.. toctree::
77
:maxdepth: 2
88

9-
charm-to-poetry
10-
charm-to-python
11-
shared-cache
9+
set-up-charmcraft
10+
manage-charms
11+
manage-a-12-factor-app-charm
12+
manage-extensions
13+
manage-resources
14+
manage-libraries
15+
manage-parts
16+
manage-the-current-charmhub-user
17+
manage-names
18+
manage-revisions
19+
manage-channels
20+
manage-tracks
21+
manage-icons
22+
manage-bundles
1223
flask-async
24+
Migrate plugins <migrate-plugins/index>
25+
Build <build-guides/index>

0 commit comments

Comments
 (0)