feat(repo): Use pdoc for document generation

.github/workflows/branch_ci.yml

@@ -115,8 +115,14 @@ jobs:
       - name: Install editable package and required dependencies
         run: uv sync
 
+        # Pydoctor is ran to find any linking errors in the docs
       - name: Build documentation
-        run: uv run pydoctor
+        run: |
+          uv run pydoctor --html-output=tmpdocs -W -q
+          PDOC_ALLOW_EXEC=1 uv run pdoc -o docs \
+            --docformat=google \
+            --logo="https://cdn.prod.website-files.com/62d92550f6774db58d441cca/6324a2038936ecda71599a8b_OCF_Logo_black_trans.png" \
+            src/nwp_consumer
 
       - name: Upload documentation
         uses: actions/upload-artifact@v4
@@ -143,7 +149,7 @@ jobs:
           fetch-depth: 0
 
       - name: Set up Buildx
-        uses: docker/setup-buildx-action@v2
+        uses: docker/setup-buildx-action@v3
 
       - name: Log in to the Container registry
         uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
@@ -165,7 +171,7 @@ jobs:
       # * Creates a multiplatform-aware image
       # * Pulls build cache from the registry
       - name: Build and push container image
-        uses: docker/build-push-action@v4
+        uses: docker/build-push-action@v6
         with:
           context: .
           file: Containerfile

.github/workflows/tagged_ci.yml

@@ -41,7 +41,7 @@ jobs:
           fetch-depth: 0
 
       - name: Set up Buildx
-        uses: docker/setup-buildx-action@v2
+        uses: docker/setup-buildx-action@v3
 
       - name: Log in to the Container registry
         uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
@@ -63,7 +63,7 @@ jobs:
       # * Creates a multiplatform-aware image
       # * Pulls build cache from the registry and pushes new cache back
       - name: Build and push container image
-        uses: docker/build-push-action@v4
+        uses: docker/build-push-action@v6
         with:
           context: .
           file: Containerfile

pyproject.toml

@@ -50,6 +50,7 @@ dev = [
     "types-pyyaml",
     # Docs
     "pydoctor >= 24.3.0",
+    "pdoc >= 15.0.0",
     # IDE support
     "python-lsp-server",
     "pylsp-mypy",
@@ -158,6 +159,7 @@ project-base-dir = "src/nwp_consumer"
 docformat = "google"
 html-output = "docs"
 theme = "classic"
+warnings-as-errors = true
 privacy = [
     "HIDDEN:**.test_*",
 ]

src/nwp_consumer/__init__.py

@@ -8,23 +8,27 @@
 
 The following environment variables can be used to configure the application:
 
-+-------------------------------+-------------------------------------+---------------------------------------------+
-| Key                           | Description                         | Default                                     |
-+===============================+=====================================+=============================================+
-| LOGLEVEL                      | The logging level for the app.      | INFO                                        |
-+-------------------------------+-------------------------------------+---------------------------------------------+
-| RAWDIR                        | The working directory for the app.  | ~/.local/cache/nwp/<REPO>/<MODEL>/raw       |
-|                               | Can be a local path or an S3 URI.   |                                             |
-+-------------------------------+-------------------------------------+---------------------------------------------+
-| ZARRDIR                       | The output directory for the app.   | ~/.local/cache/nwp/<REPO>/<MODEL>/data      |
-|                               | Can be a local path or an S3 URI.   |                                             |
-+-------------------------------+-------------------------------------+---------------------------------------------+
-| NOTIFICATION_REPOSITORY       | The notification repository to use. | stdout                                      |
-+-------------------------------+-------------------------------------+---------------------------------------------+
-| MODEL_REPOSITORY              | The model repository to use.        | ceda-metoffice-global                       |
-+-------------------------------+-------------------------------------+---------------------------------------------+
-| CONCURRENCY                   | Whether to use concurrency.         | True                                        |
-+-------------------------------+-------------------------------------+---------------------------------------------+
+.. code-block:: none
+
+    | Key                       | Description                         | Default                                     |
+    |---------------------------|-------------------------------------|---------------------------------------------|
+    | LOGLEVEL                  | The logging level for the app.      | INFO                                        |
+    |---------------------------|-------------------------------------|---------------------------------------------|
+    | RAWDIR                    | The working directory for the app.  | ~/.local/cache/nwp/<REPO>/<MODEL>/raw       |
+    |                           | Can be a local path or an S3 URI.   |                                             |
+    |---------------------------|-------------------------------------|---------------------------------------------|
+    | ZARRDIR                   | The output directory for the app.   | ~/.local/cache/nwp/<REPO>/<MODEL>/data      |
+    |                           | Can be a local path or an S3 URI.   |                                             |
+    |---------------------------|-------------------------------------|---------------------------------------------|
+    | NOTIFICATION_REPOSITORY   | The notification repository to use. | stdout                                      |
+    |---------------------------|-------------------------------------|---------------------------------------------|
+    | MODEL_REPOSITORY          | The model repository to use.        | ceda-metoffice-global                       |
+    |---------------------------|-------------------------------------|---------------------------------------------|
+    | CONCURRENCY               | Whether to use concurrency.         | True                                        |
+    |---------------------------|-------------------------------------|---------------------------------------------|
+
+There is also specific configuration variables for some model repositories.
+Refer to their documentation for more information: `nwp_consumer.internal.repositories`.
 
 
 Development Documentation
@@ -54,15 +58,15 @@
 -----------------
 
 The code is structured following principles from the `Hexagonal Architecture`_ pattern.
-In brief, this means a clear separation between the application's business logic
-- it's *core* - and the *actors* that are external to it.
+In brief, this means a clear separation between
+the application's business logic - it's *core* - and the *actors* that are external to it.
 
 The core of the services is split into three main components:
 
-- `internal.entities` - The domain classes that define the structure of the data
+- `nwp_consumer.internal.entities` - The domain classes that define the structure of the data
   that the services works with, and the business logic they contain.
-- `internal.ports` - The interfaces that define how the services interact with external actors.
-- `internal.services` - The business logic that defines how the service functions.
+- `nwp_consumer.internal.ports` - The interfaces that define how the services interact with external actors.
+- `nwp_consumer.internal.services` - The business logic that defines how the service functions.
 
 Alongside these core components are the actors, which adhere to the interfaces defined in the
 ports module. Actors come in two flavours, *driving* and *driven*.
@@ -72,9 +76,9 @@
 
 This application currently has the following defined actors:
 
-- `internal.repositories.model_repositories` (driven) - The sources of NWP data.
-- `internal.repositories.notification_repositories` (driven) - The sinks of notification data.
-- `internal.handlers.cli` (driving) - The command-line interface for the services.
+- `nwp_consumer.internal.repositories.model_repositories` (driven) - The sources of NWP data.
+- `nwp_consumer.internal.repositories.notification_repositories` (driven) - The sinks of notification data.
+- `nwp_consumer.internal.handlers.cli` (driving) - The command-line interface for the services.
 
 The actors are then responsible for implementing the abstract ports,
 and are *dependency-injected* in at runtime. This allows the services to be easily tested

src/nwp_consumer/internal/ports/repositories.py

@@ -112,21 +112,14 @@ def fetch_init_data(self, it: dt.datetime) \
     @staticmethod
     @abc.abstractmethod
     def repository() -> entities.ModelRepositoryMetadata:
-        """Metadata about the model repository.
-
-        See Also:
-            - `entities.ModelRepositoryMetadata`.
-        """
+        """Metadata about the model repository."""
         pass
 
     @staticmethod
     @abc.abstractmethod
     def model() -> entities.ModelMetadata:
-        """Metadata about the model.
-
-        See Also:
-            - `entities.ModelMetadata`.
-        """
+        """Metadata about the model."""
+        pass
 
 
 class ZarrRepository(abc.ABC):

src/nwp_consumer/internal/repositories/__init__.py

@@ -6,7 +6,7 @@
 A driven actor is an external component that is acted upon by the core logic.
 Also referred to as *secondary* actors, a driven actor represents an external
 system that the core logic interacts with. They extend the core driven ports
-(see `nwp_consumer.internal.ports.repositories`) in their implementation.
+(see `nwp_consumer.internal.ports`) in their implementation.
 
 Examples of driven or secondary actors include:
 
@@ -19,8 +19,10 @@
 
 This module contains implementations for the following driven actors:
 
-- Notification - `notification_repositories`
-- Model - `model_repositories`
+- Notification Repository - Somewhere to send notifications to
+- Model Repository - Source of NWP data
+
+Both inherit from the repository ports specified in the core via `nwp_consumer.internal.ports`.
 """
 
 from .model_repositories import (