diff --git a/docs/howto/index.rst b/docs/howto/index.rst index d018a2e76..f09a8c3dd 100644 --- a/docs/howto/index.rst +++ b/docs/howto/index.rst @@ -6,9 +6,9 @@ How-to guides .. toctree:: :maxdepth: 2 - set-up-charmcraft + manage-charmcraft manage-charms - manage-a-12-factor-app-charm + manage-12-factor-app-charms manage-extensions manage-resources manage-libraries diff --git a/docs/howto/manage-a-12-factor-app-charm.rst b/docs/howto/manage-12-factor-app-charms.rst similarity index 98% rename from docs/howto/manage-a-12-factor-app-charm.rst rename to docs/howto/manage-12-factor-app-charms.rst index 95f31299e..6734bd586 100644 --- a/docs/howto/manage-a-12-factor-app-charm.rst +++ b/docs/howto/manage-12-factor-app-charms.rst @@ -1,10 +1,10 @@ -.. _manage-a-12-factor-app-charm: +.. _manage-12-factor-app-charms: -Manage a 12-factor app charm -============================ +Manage 12-factor app charms +=========================== - See also: :external+juju:ref:`Juju | Charm ` + See also: :external+juju:ref:`Juju | Charm taxonomy ` Prepare an OCI image for a 12-factor app charm diff --git a/docs/howto/manage-channels.rst b/docs/howto/manage-channels.rst index f4d631e6f..a549ed334 100644 --- a/docs/howto/manage-channels.rst +++ b/docs/howto/manage-channels.rst @@ -3,6 +3,7 @@ Manage channels =============== + See first: :external+juju:ref:`Juju | Charm channel ` Create a channel ---------------- diff --git a/docs/howto/set-up-charmcraft.rst b/docs/howto/manage-charmcraft.rst similarity index 93% rename from docs/howto/set-up-charmcraft.rst rename to docs/howto/manage-charmcraft.rst index 0ab2864f0..c22d90a17 100644 --- a/docs/howto/set-up-charmcraft.rst +++ b/docs/howto/manage-charmcraft.rst @@ -1,6 +1,6 @@ -.. _set-up-charmcraft: +.. _manage-charmcraft: -Set up Charmcraft +Manage Charmcraft ================= @@ -148,3 +148,18 @@ To check the installed version, run: .. See more: :ref:`ref_commands_version` + + +Upgrade Charmcraft +------------------ + +If you've installed Charmcraft on Linux as a snap, it will upgrade automatically. + +Uninstall Charmcraft +-------------------- + +For an installation on Linux via snap, run: + +.. code-block:: bash + + sudo snap remove charmcraft diff --git a/docs/howto/manage-charms.rst b/docs/howto/manage-charms.rst index 548ac8ec1..83b6a339a 100644 --- a/docs/howto/manage-charms.rst +++ b/docs/howto/manage-charms.rst @@ -6,10 +6,16 @@ Manage charms See first: :external+juju:ref:`Juju | Charm `, :external+juju:ref:`Juju | Manage charms ` +.. _initialise-a-charm: Initialise a charm ------------------ +.. note:: + + **Best practice:** If you're setting up a git repository: Name it on the pattern + ``-operator``. For the charm name, see :ref:`specify-a-name`. + To initialise a charm project, create a directory for your charm, enter it, then run ``charmcraft init`` with the ``--profile`` flag followed by a suitable profile name (for machine charms: ``machine``; for Kubernetes charms: ``kubernetes``, ``simple``, or @@ -74,10 +80,24 @@ To specify that the project is a charm (as supposed to a bundle), in your type: charm +.. + + See more: :ref:`recipe-key-type` + +.. _specify-a-name: Specify a name ~~~~~~~~~~~~~~ +.. note:: + + **Best practice:** The name should be slug-oriented (ASCII lowercase letters, + numbers, and hyphens) and follow the pattern + ``[][-k8s]``. E.g., ``argo-server-k8s``. + +.. Need to add more content based on https://discourse.charmhub.io/t/charm-naming-guidelines/5364 . + + To specify a pack-and-deploy name for your charm, in your charm's ``charmcraft.yaml`` file specify the ``name`` key. E.g., @@ -210,9 +230,10 @@ charm's ``charmcraft.yaml`` file specify an item under the :ref:`links.website See more: :ref:`recipe-key-links` +.. _add-docs: -Add docs and a link to the docs -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Add docs +~~~~~~~~ If you publish your charm on Charmhub, reference documentation about the charm's resources, actions, configurations, relations, and libraries is extracted automatically. @@ -251,7 +272,7 @@ value for the ``terms`` key. E.g., Add an icon ~~~~~~~~~~~ - See :ref:`manage-icons`. + See more: :ref:`manage-icons` Add runtime details to a charm @@ -357,9 +378,10 @@ To specify device requirements, in your charm's ``charmcraft.yaml`` file specify See more: :ref:`recipe-key-devices` +.. _manage-storage: -Specify storage requirements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Manage storage +~~~~~~~~~~~~~~ To specify storage requirements, in your charm's ``charmcraft.yaml`` file specify the ``storage`` key. @@ -385,6 +407,7 @@ same machine as another charm, called its *principal*), in your charm's See more: :ref:`recipe-key-subordinate` +.. _manage-actions: Manage actions ~~~~~~~~~~~~~~ @@ -399,6 +422,7 @@ specify the ``actions`` key. See next: :external+ops:ref:`manage-actions` +.. _manage-configurations: Manage configurations ~~~~~~~~~~~~~~~~~~~~~ @@ -416,9 +440,10 @@ specify the ``config`` key. See next: :external+ops:ref:`manage-configurations` +.. _manage-relations: -Manage relations (integrations) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Manage relations +~~~~~~~~~~~~~~~~ See first: :external+juju:ref:`Juju | Relation `, :external+juju:ref:`Juju | Manage relations ` @@ -434,10 +459,9 @@ Manage relations (integrations) Specify necessary libs ~~~~~~~~~~~~~~~~~~~~~~ -.. See first: `Juju | Library <>`_ - See more: :ref:`manage-libraries` +.. _manage-secrets: Manage secrets ~~~~~~~~~~~~~~ @@ -459,6 +483,7 @@ Specify necessary parts See more: :ref:`manage-parts` +.. _pack-a-charm: Pack a charm ------------ @@ -563,7 +588,7 @@ Publish a charm on Charmhub charmcraft login - .. +.. See more: :ref:`manage-the-current-charmhub-user` diff --git a/docs/howto/manage-tracks.rst b/docs/howto/manage-tracks.rst index b6822e5d5..6ae5301e4 100644 --- a/docs/howto/manage-tracks.rst +++ b/docs/howto/manage-tracks.rst @@ -3,7 +3,7 @@ Manage tracks ============= -.. See also: :ref:`track` Add link to Juju docs > charm > channel > track + See first: :external+juju:ref:`Juju | Charm channel track ` When you register a charm name on Charmhub, you automatically get 4 channels, all with track ``latest``. However, as your charm evolves, you'll likely want to customise the @@ -16,7 +16,8 @@ new pattern. This document shows you how. Request a track guardrail ------------------------- -.. See also: :ref:`guardrail` (link to new Juju docs > charm > channel > track > guardrail) + See first: :external+juju:ref:`Juju | Charm channel track guardrail + ` To request a track guardrail, contact a Charmhub admin by creating a post on Discourse under the **charmhub requests** category, that is, here: