docs: add, refactor, and reformat discourse docs feat. charmcraft (#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]>

.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>