From d448c4494d3834679da95db479f952da9fe4cf37 Mon Sep 17 00:00:00 2001 From: Matt Culler Date: Wed, 18 Sep 2024 16:09:04 -0400 Subject: [PATCH] feat(docs): update partitions docs (#475) * feat: update partitions docs & fix autobuild path * Apply suggestions from code review * Apply suggestions from code review Co-authored-by: Michael DuBelko * fix(docs): use Michael's suggested text Co-authored-by: Michael DuBelko * Update docs/howto/partitions.rst Co-authored-by: Sergio Schvezov * docs: update other reference w/ Sergio's suggestion Co-authored-by: Sergio Schvezov --------- Co-authored-by: Michael DuBelko Co-authored-by: Sergio Schvezov --- docs/howto/partitions.rst | 60 +++++++++++++++++++++++---------------- tox.ini | 2 +- 2 files changed, 37 insertions(+), 25 deletions(-) diff --git a/docs/howto/partitions.rst b/docs/howto/partitions.rst index f3dd4d02..72d4a9d6 100644 --- a/docs/howto/partitions.rst +++ b/docs/howto/partitions.rst @@ -45,45 +45,57 @@ Required application changes To add partition support to an application, two basic changes are needed: -#. Enable the feature +#. Enable the feature. - Use the :class:`Features ` class to specify that the - application will use partitions: + In your Application subclass, override the following method and invoke the + :class:`Features ` class: .. code-block:: python from craft_parts import Features - Features.reset() - Features(enable_partitions=True) + class ExampleApplication(Application): - .. NOTE:: - The ``craft-application`` class :class:`AppFeatures - ` has a similar name and serves a similar - purpose to ``craft-parts``'s :class:`Features `, - but partitions cannot be enabled via :class:`AppFeatures - `! + ... -#. Define the list of partitions + @override + def _enable_craft_parts_features(self) -> None: + Features(enable_partitions=True) - We need to tell the :class:`LifecycleManager ` - class about our partitions, but applications do not usually directly - instantiate the LifecycleManager. + You can only be enable partitions with the :class:`Features + ` class from craft-parts. In craft-application + there's a similarly-named :class:`AppFeatures + ` class which serves a similar purpose, + but it can't enable partitions. - Instead, override your :class:`Application - `'s ``_setup_partitions`` method, and return - a list of the partitions, which will eventually be passed to the - :class:`LifecycleManager `: + .. Tip:: + In unit tests, the :class:`Features ` global + singleton may raise exceptions when successive tests repeatedly try to + enable partitions. + + To prevent these errors, reset the features at the start of each test: + + .. code-block:: python + + Features.reset() + + + +#. Define the list of partitions. + + Override the ``_setup_partitions`` method of your :class:`Application + ` class and return the list of the + partitions. .. code-block:: python - class SnackcraftApplication(Application): + class ExampleApplication(Application): - ... + ... - @override - def _setup_partitions(self, yaml_data: dict[str, Any]) -> list[str] | None: - return ["default", "kernel", "component/bar-baz"] + @override + def _setup_partitions(self, yaml_data: dict[str, Any]) -> list[str] | None: + return ["default", "kernel", "component/bar-baz"] Using the partitions ==================== diff --git a/tox.ini b/tox.ini index 1299849e..4cffea77 100644 --- a/tox.ini +++ b/tox.ini @@ -119,7 +119,7 @@ commands = sphinx-build {posargs:-b html} -W {tox_root}/docs {tox_root}/docs/_bu [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_application {tox_root}/docs {tox_root}/docs/_build/html +commands = sphinx-autobuild {posargs:-b html --open-browser --port 8080} -W --watch {tox_root}/craft_application {tox_root}/docs {tox_root}/docs/_build [testenv:lint-docs] description = Lint the documentation with sphinx-lint