feat(docs): add python and poetry plugin docs (#1940)

This adds documentation for the Python and Poetry plugins.

It builds upon #1939 and
requires canonical/craft-parts#872

NOTE: This still needs a craft-parts update for all docs rendering to
work properly, but please review what you can ITMT

---------

Co-authored-by: Michael DuBelko <michael.dubelko@gmail.com>

docs/reference/plugins/index.rst

@@ -12,6 +12,8 @@ potentially the addition of further files using the :ref:`craft_parts_dump_plugi
 
     /common/craft-parts/reference/plugins/dump_plugin
     /common/craft-parts/reference/plugins/nil_plugin
+    python_plugin
+    poetry_plugin
 
 .. warning::
    Other plugins are available from :external+craft-parts:ref:`craft-parts <plugins>`,

docs/reference/plugins/poetry-charmcraft.yaml

@@ -0,0 +1,13 @@
+name: my-charm
+type: charm
+title: My poetry charm
+summary: An operator charm using Poetry.
+description: |
+  An operator charm that uses Poetry for its project.
+base: ubuntu@24.04
+platforms:
+  amd64:
+parts:
+  my-charm:
+    source: .
+    plugin: poetry

docs/reference/plugins/poetry_plugin.rst

@@ -0,0 +1,51 @@
+.. _craft_parts_poetry_plugin:
+
+Poetry plugin
+=============
+
+The Poetry plugin can be used for Python charms written using `Poetry`_ and the
+`Operator framework`_.
+
+.. include:: /common/craft-parts/reference/plugins/poetry_plugin.rst
+   :start-after: .. _craft_parts_poetry_plugin-keywords:
+   :end-before: .. _craft_parts_poetry_plugin-environment_variables:
+
+python-keep-bins
+~~~~~~~~~~~~~~~~
+**Type**: boolean
+**Default**: False
+
+Whether to keep python scripts in the virtual environment's ``bin`` directory.
+
+.. include:: /common/craft-parts/reference/plugins/poetry_plugin.rst
+   :start-after: .. _craft_parts_poetry_plugin-environment_variables:
+   :end-before: .. _poetry-details-end:
+
+How it works
+------------
+
+During the build step, the plugin performs the following actions:
+
+1. It creates a virtual environment in the
+   :ref:`${CRAFT_PART_INSTALL}/venv <craft_parts_step_execution_environment>` directory.
+2. It uses :command:`poetry export` to create a ``requirements.txt`` in the project's
+   build directory.
+3. It uses :command:`pip` to install the packages referenced in ``requirements.txt``
+   into the virtual environment. Undeclared dependencies are ignored.
+4. It copies any existing ``src`` and ``lib`` directories from your charm project into
+   the final charm.
+5. It runs :command:`pip check` to ensure the virtual environment is consistent.
+
+Example
+-------
+
+The following ``charmcraft.yaml`` file can be used with a poetry project to build
+the charm for Ubuntu 24.04:
+
+.. literalinclude:: poetry-charmcraft.yaml
+   :language: yaml
+
+
+.. _Poetry: https://python-poetry.org
+.. _dependency groups: https://python-poetry.org/docs/managing-dependencies#dependency-groups
+.. _environment variables to configure Poetry: https://python-poetry.org/docs/configuration/#using-environment-variables

docs/reference/plugins/python-charmcraft.yaml

@@ -0,0 +1,15 @@
+name: my-charm
+type: charm
+title: My Python charm
+summary: An operator charm that uses the python plugin
+description: |
+  An operator charm using the Python plugin.
+base: ubuntu@24.04
+platforms:
+  amd64:
+parts:
+  my-charm:
+    source: .
+    plugin: python
+    python-requirements:
+      - requirements.txt

docs/reference/plugins/python_plugin.rst

@@ -0,0 +1,62 @@
+.. _craft_parts_python_plugin:
+
+Python plugin
+=============
+
+The Python plugin builds charms written in Python. It's typically
+used in conjunction with the `Operator framework`_.
+
+.. include:: /common/craft-parts/reference/plugins/python_plugin.rst
+   :start-after: .. _craft_parts_python_plugin-keywords:
+   :end-before: .. _craft_parts_python_plugin-environment_variables:
+
+python-keep-bins
+~~~~~~~~~~~~~~~~
+**Type**: boolean
+**Default**: False
+
+Whether to keep python scripts in the virtual environment's ``bin`` directory.
+
+.. include:: /common/craft-parts/reference/plugins/python_plugin.rst
+   :start-after: .. _craft_parts_python_plugin-environment_variables:
+   :end-before: .. _python-details-begin:
+
+Dependencies
+------------
+
+This plugin creates a Python virtual environment in the ``venv`` directory of your
+charm using the version of Python included with your base and the requirements files
+provided in the ``python-requirements`` key.
+
+.. note::
+   The python plugin prevents :command:`pip` from installing dependencies for the
+   required packages. Therefore, requirements must include indirect dependencies as
+   well as direct dependencies. It is recommended that you use a tool such as
+   :command:`pip-compile` or :command:`uv` to manage the contents of your
+   ``requirements.txt`` file.
+
+How it works
+------------
+
+During the build step, the plugin performs the following actions:
+
+1. It creates a virtual environment in the
+   :ref:`${CRAFT_PART_INSTALL}/venv <craft_parts_step_execution_environment>`
+   directory.
+2. It uses :command:`pip` to install the required Python packages specified
+   by the ``python-requirements``, ``python-constraints`` and ``python-packages``
+   keys.
+4. It copies any existing ``src`` and ``lib`` directories from your charm project into
+   the final charm.
+
+
+Example
+-------
+
+The following ``charmcraft.yaml`` file can be used with a standard charm structure
+to build a charm for Ubuntu 24.04:
+
+.. literalinclude:: python-charmcraft.yaml
+   :language: yaml
+
+

docs/reuse/links.txt

@@ -7,6 +7,7 @@
 .. _`OCI archive format`: https://github.com/opencontainers/image-spec/blob/main/layer.md#distributable-format
 .. _OCI_image_spec: https://github.com/opencontainers/image-spec/blob/main/spec.md
 .. _`OCI layers`: https://github.com/opencontainers/image-spec/blob/main/layer.md
+.. _`Operator framework`: https://juju.is/docs/sdk/ops
 .. _LXD: https://canonical.com/lxd
 .. _Multipass: https://multipass.run/docs
 .. _`Open Container Initiative`: https://opencontainers.org/