From aec888600534c136e5a185fe9d8f8ac64e58861d Mon Sep 17 00:00:00 2001
From: Alex Lowe <alex.lowe@canonical.com>
Date: Wed, 28 Aug 2024 13:52:50 -0400
Subject: [PATCH] feat(docs): add poetry plugin reference (#830)

---
 .../reference/plugins/poetry_plugin.rst       | 104 ++++++++++++++++++
 docs/reference/plugins.rst                    |   1 +
 tox.ini                                       |   3 +-
 3 files changed, 107 insertions(+), 1 deletion(-)
 create mode 100644 docs/common/craft-parts/reference/plugins/poetry_plugin.rst

diff --git a/docs/common/craft-parts/reference/plugins/poetry_plugin.rst b/docs/common/craft-parts/reference/plugins/poetry_plugin.rst
new file mode 100644
index 000000000..2aab76577
--- /dev/null
+++ b/docs/common/craft-parts/reference/plugins/poetry_plugin.rst
@@ -0,0 +1,104 @@
+.. _craft_parts_poetry_plugin:
+
+Poetry plugin
+=============
+
+The Poetry plugin can be used for Python projects that use the `Poetry`_ build system.
+
+Keywords
+--------
+
+This plugin uses the common :ref:`plugin <part-properties-plugin>` keywords as
+well as those for :ref:`sources <part-properties-sources>`.
+
+Additionally, this plugin provides the plugin-specific keywords defined in the
+following sections.
+
+poetry-with:
+~~~~~~~~~~~~
+**Type:** list of strings
+
+Extra `dependency groups`_ to use other than the defaults.
+
+Environment variables
+---------------------
+
+This plugin also sets environment variables in the build environment. User-set
+environment variables will override these values. Users may also set
+`environment variables to configure Poetry`_ using the
+:ref:`build-environment <build_environment>` key.
+
+PARTS_PYTHON_INTERPRETER
+~~~~~~~~~~~~~~~~~~~~~~~~
+**Default value:** python3
+
+Either the interpreter binary to search for in ``PATH`` or an absolute path to
+the interpreter (e.g. ``${CRAFT_STAGE}/bin/python``).
+
+PARTS_PYTHON_VENV_ARGS
+~~~~~~~~~~~~~~~~~~~~~~
+**Default value:** (empty string)
+
+Additional arguments passed to ``python -m venv``.
+
+.. _poetry-details-begin:
+
+Dependencies
+------------
+
+Python
+~~~~~~
+
+By default this plugin uses the system Python when available and appropriate to
+use, using the same logic as the
+:ref:`Python plugin <craft_parts_python_plugin>`. If a different interpreter is
+desired, it must be made available in the build environment (including the ``venv``
+module) and its path must be included in the ``PATH`` environment variable.
+Use of ``python3-<python-package>`` in stage-packages will force the inclusion
+of the Python interpreter.
+
+Poetry
+~~~~~~
+
+By default, this plugin gets Poetry from the ``python3-poetry`` package on the build
+system. If that is not desired (for example, if a newer version  of Poetry is
+required), a ``poetry-deps`` part can install poetry in the build system. Any parts
+that use the Poetry plugin must run ``after`` the ``poetry-deps`` part:
+
+.. code-block:: yaml
+
+  parts:
+    poetry-deps:
+      plugin: nil
+      build-packages:
+        - curl
+        - python3
+      build-environment:
+        - POETRY_VERSION: "1.8.0"
+      override-pull: |
+        curl -sSL https://install.python-poetry.org | python3 -
+    my-project:
+      plugin: poetry
+      source: .
+      after: [poetry-deps]
+
+.. _poetry-details-end:
+
+How it works
+------------
+
+During the build step, the plugin performs the following actions:
+
+1. It creates a virtual environment directly into the ``${CRAFT_PART_INSTALL}``
+   directory.
+2. It uses :command:`poetry export` to create a ``requirements.txt`` file in the
+   project's build directory.
+3. It uses :command:`pip` to install the packages referenced in ``requirements.txt``
+   into the virtual environment, without any additional dependencies.
+4. It uses :command:`pip` to install the source package without any additional
+   dependencies.
+5. It runs :command:`pip check` to ensure the virtual environment is consistent.
+
+.. _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
diff --git a/docs/reference/plugins.rst b/docs/reference/plugins.rst
index 64deab45c..5552ef656 100644
--- a/docs/reference/plugins.rst
+++ b/docs/reference/plugins.rst
@@ -21,6 +21,7 @@ lifecycle.
    /common/craft-parts/reference/plugins/meson_plugin.rst
    /common/craft-parts/reference/plugins/nil_plugin.rst
    /common/craft-parts/reference/plugins/npm_plugin.rst
+   /common/craft-parts/reference/plugins/poetry_plugin.rst
    /common/craft-parts/reference/plugins/python_plugin.rst
    /common/craft-parts/reference/plugins/qmake_plugin.rst
    /common/craft-parts/reference/plugins/rust_plugin.rst
diff --git a/tox.ini b/tox.ini
index 7a101adb9..f375ec55b 100644
--- a/tox.ini
+++ b/tox.ini
@@ -127,7 +127,8 @@ commands = sphinx-build {posargs:-b html} {tox_root}/docs {tox_root}/docs/_build
 [testenv:autobuild-docs]
 description = Build documentation with an autoupdating server
 base = docs
-commands = sphinx-autobuild {posargs:-b html --open-browser --port 8080} -W --watch {tox_root}/craft-parts {tox_root}/docs {tox_root}/docs/_build
+allowlist_externals = make
+commands = make -C docs rundocs
 
 [testenv:lint-docs]
 description = Lint the documentation with sphinx-lint