Skip to content

Commit

Permalink
feat(docs): update partitions docs (#475)
Browse files Browse the repository at this point in the history
* feat: update partitions docs & fix autobuild path

* Apply suggestions from code review

* Apply suggestions from code review

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

* fix(docs): use Michael's suggested text

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

* Update docs/howto/partitions.rst

Co-authored-by: Sergio Schvezov <sergio.schvezov@canonical.com>

* docs: update other reference w/ Sergio's suggestion

Co-authored-by: Sergio Schvezov <sergio.schvezov@canonical.com>

---------

Co-authored-by: Michael DuBelko <michael.dubelko@gmail.com>
Co-authored-by: Sergio Schvezov <sergio.schvezov@canonical.com>
  • Loading branch information
3 people authored Sep 18, 2024
1 parent e546fae commit d448c44
Show file tree
Hide file tree
Showing 2 changed files with 37 additions and 25 deletions.
60 changes: 36 additions & 24 deletions docs/howto/partitions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <craft_parts.Features>` class to specify that the
application will use partitions:
In your Application subclass, override the following method and invoke the
:class:`Features <craft_parts.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
<craft_application.AppFeatures>` has a similar name and serves a similar
purpose to ``craft-parts``'s :class:`Features <craft_parts.Features>`,
but partitions cannot be enabled via :class:`AppFeatures
<craft_application.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 <craft_parts.LifecycleManager>`
class about our partitions, but applications do not usually directly
instantiate the LifecycleManager.
You can only be enable partitions with the :class:`Features
<craft_parts.Features>` class from craft-parts. In craft-application
there's a similarly-named :class:`AppFeatures
<craft_application.AppFeatures>` class which serves a similar purpose,
but it can't enable partitions.

Instead, override your :class:`Application
<craft_application.Application>`'s ``_setup_partitions`` method, and return
a list of the partitions, which will eventually be passed to the
:class:`LifecycleManager <craft_parts.LifecycleManager>`:
.. Tip::
In unit tests, the :class:`Features <craft_parts.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
<craft_application.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
====================
Expand Down
2 changes: 1 addition & 1 deletion tox.ini
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit d448c44

Please sign in to comment.