docs: poetry plugin reference

docs/common/craft-parts/reference/plugins/poetry_plugin.rst

@@ -0,0 +1,105 @@
+.. _craft_parts_poetry_plugin:
+
+Poetry plugin
+=============
+
+**Version**: 2.1
+
+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 <poetry-config-env-vars>`_ using the
+:ref:`build-environment <build_environment>` key.
+
+PARTS_PYTHON_INTERPRETER
+~~~~~~~~~~~~~~~~~~~~~~~~
+**Default value:** python3
+
+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 for venv.
+
+.. _poetry-details-begin:
+
+Dependencies
+------------
+
+Python
+~~~~~~
+
+By default this plugin uses Python from the base when it is 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
+.. _poetry-config-env-vars: https://python-poetry.org/docs/configuration/#using-environment-variables

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

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