docs: update docs for 5.0.0 (#700)

Co-authored-by: Michael DuBelko <[email protected]>

Author: lengau

craft_application/pytest_plugin.py

@@ -35,8 +35,8 @@
 def debug_mode() -> None:
     """Ensure that the application is in debug mode, raising exceptions from run().
 
-    This fixture is automatically used. To disable debug mode for specific tests that
-    require it, use the :py:func:`production_mode` fixture.
+    This fixture is automatically used. To disable debug mode for specific tests,
+    use the :py:func:`production_mode` fixture.
     """
     os.environ["CRAFT_DEBUG"] = "1"
 
@@ -98,7 +98,7 @@ def fake_host_architecture(
     """Run this test as though running on each supported architecture.
 
     This parametrized fixture provides architecture values for all supported
-    architectures, simulating as though the application is running on that architecture.
+    architectures, simulating running on that architecture.
     This fixture is limited to setting the architecture within this python process.
     """
     arch: craft_platforms.DebianArchitecture = request.param
@@ -139,7 +139,7 @@ def in_project_path(
 ) -> pathlib.Path:
     """Run the test inside the project path.
 
-    Changes the working directory of the test to use the project path.
+    This fixture changes the working directory of the test to use the project path.
     Best to use with ``pytest.mark.usefixtures``
     """
     monkeypatch.chdir(project_path)

docs/reference/changelog.rst

@@ -4,18 +4,17 @@
 Changelog
 *********
 
-5.0.0 (2025-Mon-DD)
--------------------
+5.0.0 (2025-03-26)
+------------------
 
 Services
 ========
 
-- A new :doc:`services/project` now handles the creation and management of the project
-  for this run of the application.
+- A new :doc:`services/project` now handles project loading and rendering. Services
+  and commands can use this to get a project. The abstract ``ProjectService`` is no
+  longer available for inheritance.
 - Setting the arguments for a service using the service factory's ``set_kwargs`` is
-  deprecated. Use ``update_kwargs`` instead or file `an issue
-  <https://github.com/canonical/craft-application/issues/new?template=bug.yaml>`_
-  if you still need this method.
+  deprecated. Use ``update_kwargs`` instead.
 
 Testing
 =======
@@ -33,9 +32,9 @@ Breaking changes
   designate that they require a project, but should instead use the
   :py:meth:`~craft_application.services.project.ProjectService.get()` method of the
   ``ProjectService`` to retrieve the project. It will error accordingly.
-- The ``BuildPlanner`` class has been replaced with the
+- The ``BuildPlanner`` pydantic model has been replaced with the
   :py:class:`~craft_application.services.services.buildplan.BuildPlanService`
-- ``BuildInfo`` is replaced with
+- The internal ``BuildInfo`` model is replaced with
   :external+craft-platforms:class:`craft_platforms.BuildInfo`
 
 For a complete list of commits, check out the `5.0.0`_ release on GitHub.

docs/reference/pytest-plugin.rst

@@ -3,8 +3,7 @@
 pytest plugin
 =============
 
-craft-application includes a `pytest`_ plugin to help ease the testing of apps that use
-it as a framework.
+The `pytest`_ plugin helps ease the testing of apps that use craft-application.
 
 By default, this plugin sets the application into debug mode, meaning the
 :py:meth:`~craft_application.Application.run()` method will re-raise generic exceptions.
@@ -26,11 +25,11 @@ Fixtures
 .. autofunction:: in_project_path
 
 Auto-used fixtures
-~~~~~~~~~~~~~~~~~~
+------------------
 
 Some fixtures are automatically enabled for tests, changing the default behaviour of
-applications during the testing process. This is kept to a minimum, but is done when
-the standard behaviour could cause subtle testing issues.
+applications during the testing process. Each auto-use fixture changes the default
+behaviour of Craft Application during testing.
 
 .. autofunction:: debug_mode
 

docs/reference/services/project.rst

@@ -8,34 +8,29 @@ The ``ProjectService`` is a service for handling access to the project.
 Project loading
 ---------------
 
-The project service is responsible for loading, validating and rendering the project
-file to a :py:class:`~craft_application.models.Project` model. While the service can
-render a project as though it is running on any architecture and building for
-any platform or architecture, the most common use case is to render the project
-as though running on the current architecture, for the targeted platform.
-Here, the steps taken are as follows:
-
-.. How do I make this numbered?
-.. contents::
-    :class: this-will-duplicate-information-and-it-is-still-useful-here
-    :local:
+The Project service handles loading, validating and rendering the project
+file to a :py:class:`~craft_application.models.Project` model. The most common use
+case is to render the project as though running on the host's architecture, for
+the targeted platform. However, it can also  render a project as though it is
+running on any architecture and building for any platform or architecture.
+
+The rendering process follows these steps:
 
 Configure the ProjectService
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The first step is for the ``Application`` to configure the project service. This means
-several things:
+The first step is for the ``Application`` to configure the project service. It:
 
 1. Set the project directory location. This is done by passing a directory on
    instantiation.
-2. Set any ``platform`` and ``build_for`` hints. This is done using the ``configure``
-   method.
+2. Set any ``platform`` and ``build_for`` hints. This is done using the
+   ``configure()`` method.
 
 Find the project file
 ~~~~~~~~~~~~~~~~~~~~~
 
 Once a project directory is declared,
-:py:meth:`ProjectService.resolve_project_file_path` can be used to find the path to the
+:py:meth:`ProjectService.resolve_project_file_path` finds the path to the
 actual project file. By default, this is simply ``<app name>.yaml`` in the project
 directory. However, applications may override this if they need to search for the
 project file at other locations.
@@ -46,42 +41,42 @@ Parse the project file YAML
 Once the project file is found, it is parsed as a `YAML`_ file. The file has additional
 requirements beyond being a valid YAML document:
 
-1. A file may only contain a single document.
-2. The top level of this document must be a map whose keys are strings.
+1. It must contain only a single document.
+2. Its top level must be a map whose keys are strings.
 
 Validate grammar
 ~~~~~~~~~~~~~~~~
 
-At this step, any user-added grammar is validated using
-:external+craft-grammar:doc:`Craft Grammar <index>`. No grammar is applied yet.
+In this step, any user-added grammar is validated using
+:external+craft-grammar:doc:`Craft Grammar <index>`. No grammar is processed yet.
 
 Perform application-specific transforms
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 At this step, any application-specific transformations of the document are applied
-using the :py:meth:`ProjectService._app_preprocess_project` method. By default,
+by the :py:meth:`ProjectService._app_preprocess_project` method. By default,
 nothing happens here.
 
 The project dict at this state is available using the
-:py:meth:`ProjectService._preprocess` protected method. ``_preprocess`` calls
-``_app_preprocess_project`` as the last step of processing before returning the
+:py:meth:`ProjectService._preprocess` protected method. ``_preprocess()`` calls
+``_app_preprocess_project()`` as the last step of processing before returning the
 pre-processed project dict.
 
-Expand environment
-~~~~~~~~~~~~~~~~~~
+Expand the environment
+~~~~~~~~~~~~~~~~~~~~~~
 
 Next, :external+craft-parts:func:`craft_parts.expand_environment` is called to replace
 global parts variables with their expected values.
 
 Process parts grammar
 ~~~~~~~~~~~~~~~~~~~~~
 
-At this point, grammar is processed for each part defined. This includes parts added
+At this point, grammar is processed for each part. This includes parts added
 during the application-specific transforms step, meaning that transforms may add
 grammar-aware syntax if needed.
 
-Validate Pydantic model
-~~~~~~~~~~~~~~~~~~~~~~~
+Validate the Pydantic model
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A Pydantic model of the project is loaded, validating more thoroughly.