docs: add, refactor, and reformat discourse docs feat. charmcraft

.editorconfig

@@ -27,10 +27,13 @@ tab_width = 2
 indent_size = 2
 max_line_length = off
 
-[{*.markdown,*.md,*.rst}]
+[{*.markdown,*.md}]
 max_line_length = off
 ij_visual_guides = none
 
+[{*.rst}]
+max_line_length = 88
+
 [{*.toml,Cargo.lock,Cargo.toml.orig,Gopkg.lock,Pipfile,poetry.lock}]
 max_line_length = off
 

.gitignore

@@ -72,9 +72,10 @@ instance/
 # Sphinx documentation
 docs/_build/
 # Auto-generated command reference
-/docs/reference/commands/
-/docs/reference/_autosummary/
-/docs/common/craft-parts
+docs/reference/commands/
+!docs/reference/commands/index.rst
+docs/reference/_autosummary/
+docs/common/craft-parts
 
 # PyBuilder
 target/

common.mk

@@ -194,7 +194,7 @@ docs:  ## Build documentation
 
 .PHONY: docs-auto
 docs-auto:  ## Build and host docs with sphinx-autobuild
-	uv run --extra docs sphinx-autobuild -b html --open-browser --port=8080 --ignore *.kate-swp --ignore docs/reference/commands/** --watch $(PROJECT) $(DOCS) $(DOCS)/_build
+	uv run --extra docs sphinx-autobuild -b html --open-browser --port=8080 --ignore *.kate-swp --ignore docs/reference/commands/ --watch $(PROJECT) $(DOCS) $(DOCS)/_build
 
 .PHONY: pack-pip
 pack-pip:  ##- Build packages for pip (sdist, wheel)

docs/conf.py

@@ -88,11 +88,13 @@
     # documents (so they generate "duplicate label" errors) or they aren't
     # used in this documentation at all (so they generate "unreferenced"
     # errors).
+    "explanation/index.rst",
     "common/craft-parts/explanation/lifecycle.rst",
     "common/craft-parts/explanation/overlay_parameters.rst",
     "common/craft-parts/explanation/overlays.rst",
     "common/craft-parts/explanation/parts.rst",
     "common/craft-parts/explanation/how_parts_are_built.rst",
+    "common/craft-parts/explanation/dump_plugin.rst",
     "common/craft-parts/explanation/overlay_step.rst",
     "common/craft-parts/how-to/craftctl.rst",
     "common/craft-parts/how-to/include_files.rst",
@@ -113,13 +115,21 @@
     "common/craft-parts/reference/plugins/qmake_plugin.rst",
     "common/craft-parts/reference/plugins/rust_plugin.rst",
     "common/craft-parts/reference/plugins/scons_plugin.rst",
+    "common/craft-parts/reference/plugins/go_plugin.rst",
+    "common/craft-parts/reference/plugins/go_use_plugin.rst",
+    "common/craft-parts/reference/plugins/uv_plugin.rst",
     # Extra non-craft-parts exclusions can be added after this comment
 ]
 
 rst_epilog = """
 .. include:: /reuse/links.txt
 """
 
+# MyST-specific settings
+
+suppress_warnings = ["myst.domains"]  # Suppresses false warnings about missing methods
+myst_heading_anchors = 4  # Autogenerates anchors for MD headings
+
 autodoc_default_options = {"exclude-members": "model_post_init"}
 
 # region Options for extensions
@@ -129,6 +139,7 @@
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "craft-parts": ("https://canonical-craft-parts.readthedocs-hosted.com/en/latest/", None),
+    "ops": ("https://ops.readthedocs.io/en/latest/", None),
     "rockcraft": ("https://documentation.ubuntu.com/rockcraft/en/stable/", None),
 }
 # See also:

docs/explanation/index.rst

@@ -1,18 +1,6 @@
 .. _explanation:
 
 Explanation
-***********
+===========
 
-As Charmcraft is a part of the `Juju Charm SDK <https://juju.is/docs/sdk>`_, most
-explanation is hosted on the `Charm SDK docs <https://juju.is/docs/sdk/explanation>`_.
-
-.. toctree::
-   :maxdepth: 1
-
-   /common/craft-parts/explanation/dump_plugin
-   /common/craft-parts/explanation/filesets
-   lifecycle
-
-
-`Charm SDK docs <https://juju.is/docs/sdk/explanation>`_
-========================================================
+.. toctree

docs/howto/build-guides/index.rst

@@ -0,0 +1,11 @@
+.. _howto-build-guides:
+
+Build guides
+============
+
+.. toctree::
+   :maxdepth: 2
+
+   Cache intermediate build artefacts <shared-cache>
+   Pack a hook-based charm with Charmcraft <pack-a-hooks-based-charm-with-charmcraft>
+   Pack a reactive charm with Charmcraft <pack-a-reactive-charm-with-charmcraft>

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

@@ -0,0 +1,120 @@
+.. _pack-a-hooks-based-charm-with-charmcraft:
+
+How to pack a hooks-based charm with Charmcraft
+===============================================
+
+    Introduced in Charmcraft 1.4
+
+    See first: :external+ops:ref:`turn-a-hooks-based-charm-into-an-ops-charm`
+
+Suppose you have a legacy hooks-only charm, for example, `tiny-bash
+<https://github.com/erik78se/tiny-bash>`_, which you can clone with:
+
+.. code-block:: bash
+
+    git clone https://github.com/erik78se/tiny-bash
+
+To make it packable by Charmcraft, all you need to do is navigate inside the charm
+directory and create a ``charmcraft.yaml`` file with the part definition for a
+hooks-based charm, as shown below:
+
+.. code-block:: yaml
+
+    type: charm
+
+    bases:
+      - build-on:
+        - name: "ubuntu"
+          channel: "20.04"
+        run-on:
+        - name: "ubuntu"
+          channel: "20.04"
+
+    parts:
+      tiny-bash:
+        plugin: dump
+        source: .
+        prime:
+          - LICENSE
+          - README.md
+          - config.yaml
+          - copyright
+          - hooks
+          - icon.svg
+          - metadata.yaml
+
+After this, you can pack your charm with ``charmcraft pack``, as usual:
+
+.. code-block:: bash
+
+   charmcraft pack
+
+If successful, the result should look like the following.
+
+.. terminal::
+
+    Charms packed:
+        tiny-bash_ubuntu-20.04-amd64.charm
+
+The charm file should contain all the files listed in the ``prime`` section of the
+``tiny-bash`` part and the charm manifest.
+
+.. code-block:: bash
+
+    unzip -l tiny-bash_ubuntu-20.04-amd64.charm
+
+.. terminal::
+
+    Archive:  tiny-bash_ubuntu-20.04-amd64.charm
+      Length      Date    Time    Name
+    ---------  ---------- -----   ----
+          423  2021-11-12 19:37   metadata.yaml
+          431  2021-11-12 19:37   README.md
+           12  2021-11-12 19:37   config.yaml
+         3693  2021-11-12 19:37   icon.svg
+           38  2021-11-12 19:37   copyright
+          261  2021-11-12 20:08   manifest.yaml
+        34523  2021-11-12 19:37   LICENSE
+          381  2021-11-12 19:37   hooks/update-status
+          346  2021-11-12 19:37   hooks/start
+         1294  2021-11-12 19:37   hooks/shared-fs-relation-changed
+          563  2021-11-12 19:37   hooks/stop
+          497  2021-11-12 19:37   hooks/leader-elected
+          447  2021-11-12 19:37   hooks/install
+          417  2021-11-12 19:37   hooks/leader-settings-changed
+          811  2021-11-12 19:37   hooks/upgrade-charm
+          625  2021-11-12 19:37   hooks/config-changed
+    ---------                     -------
+        44762                     16 files
+
+And you can also deploy your application with ``juju deploy``, as usual:
+
+.. code-block:: bash
+
+   juju deploy ./tiny-bash_ubuntu-20.04-amd64.charm
+
+.. terminal::
+
+    Located local charm "tiny-bash", revision 0
+    Deploying "tiny-bash" from local charm "tiny-bash", revision 0
+
+If successful, the result should look as below, i.e., with the application status
+active.
+
+.. code-block:: bash
+
+    juju status
+
+.. terminal::
+
+    Model    Controller           Cloud/Region         Version  SLA          Timestamp
+    default  localhost-localhost  localhost/localhost  2.9.12   unsupported  17:23:23-03:00
+
+    App        Version  Status  Scale  Charm      Store  Channel  Rev  OS      Message
+    tiny-bash           active      1  tiny-bash  local             0  ubuntu  update-status ran: 20:22
+
+    Unit          Workload  Agent  Machine  Public address  Ports  Message
+    tiny-bash/0*  active    idle   0        10.2.17.31             update-status ran: 20:22
+
+    Machine  State    DNS         Inst id        Series  AZ  Message
+    0        started  10.2.17.31  juju-55481c-0  focal       Running

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

@@ -0,0 +1,35 @@
+.. _pack-a-reactive-charm-with-charmcraft:
+
+How to pack a reactive charm with Charmcraft
+==================================================
+
+  Introduced in Charmcraft 1.4.
+
+
+..  See also: -
+..   {ref}\ ``How to set up a charm project <how-to-set-up-a-charm-project>``
+..   -
+..   {ref}\ ``How to pack your charm using Charmcraft <how-to-pack-a-charm>``
+..   - {ref}\ ``About charm types, by creation type <charm-taxonomy>``
+
+To pack a legacy reactive charm with Charmcraft, in the charm directory create a
+``charmcraft.yaml`` file with the part definition for a reactive-based charm:
+
+.. code-block:: yaml
+
+   type: "charm"
+   bases:
+     - build-on:
+         - name: "ubuntu"
+           channel: "20.04"
+       run-on:
+         - name: "ubuntu"
+           channel: "20.04"
+   parts:
+     charm:
+       source: .
+       plugin: reactive
+       build-snaps: [charm]
+
+Done. Now you can go ahead and pack your reactive-based charm with Charmcraft
+in the usual way using ``charmcraft pack``.

docs/howto/index.rst

@@ -1,12 +1,25 @@
-.. _howto:
+.. _how-to-guides:
 
-How-To
-******
+How-to guides
+=============
 
 .. toctree::
    :maxdepth: 2
 
-   charm-to-poetry
-   charm-to-python
-   shared-cache
+   set-up-charmcraft
+   manage-charms
+   manage-a-12-factor-app-charm
+   manage-extensions
+   manage-resources
+   manage-libraries
+   manage-parts
+   manage-the-current-charmhub-user
+   manage-names
+   manage-revisions
+   manage-channels
+   manage-tracks
+   manage-icons
+   manage-bundles
    flask-async
+   Migrate plugins <migrate-plugins/index>
+   Build <build-guides/index>