Added (first version of) sample Hummingbird app. (#4)

This PR contains the work done to:
* Implemented a basic `Hummingbird` application in which to integrate the `HummingbirdDocC` library.
* Added the *ArgumentParser* package dependency to the `Package.swift` file;
* Added a new *sample* target to the `Package.swift` file;
* Added library and documentation tasks to the `Makefile` file.

Reviewed-on: #4
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>

Samples/HummingbirdDocC/App/Builders/AppBuilder.swift

@@ -0,0 +1,86 @@
+// ===----------------------------------------------------------------------===
+//
+// This source file is part of the Hummingbird DocC Middleware open source project
+//
+// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors
+//
+// ===----------------------------------------------------------------------===
+
+import class Hummingbird.Router
+
+import protocol Hummingbird.ApplicationProtocol
+
+import struct Hummingbird.Application
+import struct Hummingbird.BasicRequestContext
+import struct Hummingbird.BindAddress
+import struct Hummingbird.LogRequestsMiddleware
+import struct HummingbirdDocC.DocCConfiguration
+import struct HummingbirdDocC.DocCMiddleware
+import struct Logging.Logger
+
+struct AppBuilder {
+    
+    // MARK: Properties
+    
+    /// A type that interacts with the logging system.
+    private let logger: Logger
+    
+    // MARK: Initializers
+    
+    /// Initializes this builder.
+    /// - Parameter logger: A type that interacts with the logging system.
+    init(logger: Logger) {
+        self.logger = logger
+    }
+    
+    // MARK: Functions
+    
+    func callAsFunction(
+        _ arguments: AppArguments
+    ) -> some ApplicationProtocol {
+        return Application(
+            router: router(),
+            configuration: .init(
+                address: .hostname(
+                    arguments.hostname,
+                    port: arguments.port
+                )
+            ),
+            logger: logger
+        )
+    }
+    
+}
+
+// MARK: - Helpers
+
+private extension AppBuilder {
+    
+    // MARK: Type aliases
+    
+    typealias AppRequestContext = BasicRequestContext
+    
+    // MARK: Functions
+    
+    func router() -> Router<AppRequestContext> {
+        let router = Router()
+        
+        router.addMiddleware {
+            LogRequestsMiddleware(logger.logLevel)
+            DocCMiddleware (
+                configuration: DocCConfiguration(
+                    uriRoot: "/archives",
+                    folderRoot: "Samples/HummingbirdDocC/Archives"
+                ),
+                logger: logger
+            )
+        }
+        
+        return router
+    }
+    
+}

Samples/HummingbirdDocC/App/Parameters/SampleAppArguments.swift

@@ -0,0 +1,43 @@
+// ===----------------------------------------------------------------------===
+//
+// This source file is part of the Hummingbird DocC Middleware open source project
+//
+// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors
+//
+// ===----------------------------------------------------------------------===
+
+import protocol ArgumentParser.ParsableArguments
+
+import struct ArgumentParser.Option
+import struct Logging.Logger
+
+extension SampleApp {
+    /// A type that conforms to the ``AppArguments`` and the `ParsableArguments` protocols, which contains the input parameters required for the
+    /// execution of the sample executable.
+    struct Arguments: AppArguments, ParsableArguments {
+        
+        // MARK: Properties
+
+        @Option(
+            name: .shortAndLong,
+            help: "A label given to the sample app for the sole purpose of identification within a communications channel."
+        )
+        var hostname: String = "127.0.0.1"
+    
+        @Option(
+            name: .shortAndLong,
+            help: "A port number assigned to the sample app from where the app either sends or receives data."
+        )
+        var port: Int = 8080
+        
+        @Option(
+            name: .long,
+            help: "A log level to configure in a type that interacts with the logging system."
+        )
+        var logLevel: Logger.Level = .trace
+    }
+}

Samples/HummingbirdDocC/App/Protocols/AppArguments.swift

@@ -0,0 +1,40 @@
+// ===----------------------------------------------------------------------===
+//
+// This source file is part of the Hummingbird DocC Middleware open source project
+//
+// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors
+//
+// ===----------------------------------------------------------------------===
+
+import protocol ArgumentParser.ExpressibleByArgument
+
+import struct Logging.Logger
+
+/// A protocol that defines the input arguments the sample executable requires to run.
+protocol AppArguments {
+    
+    // MARK: Properties
+    
+    /// A label given to the sample app to identify it within a communications channel.
+    var hostname: String { get }
+    
+    /// A port number assigned to the sample app from where the app either sends or receives data.
+    var port: Int { get }
+    
+    /// A log level to configure in a type that interacts with the logging system.
+    var logLevel: Logger.Level { get }
+    
+}
+
+// MARK: - Conformances
+
+/// Extends the `Logger.Level` type so it can be used as an argument.
+#if hasFeature(RetroactiveAttribute)
+extension Logger.Level: @retroactive ExpressibleByArgument {}
+#else
+extension Logger.Level: ExpressibleByArgument {}
+#endif

Samples/HummingbirdDocC/App/SampleApp.swift

@@ -0,0 +1,48 @@
+// ===----------------------------------------------------------------------===
+//
+// This source file is part of the Hummingbird DocC Middleware open source project
+//
+// Copyright (c) 2025 Röck+Cöde VoF. and the Hummingbird DocC Middleware project authors
+// Licensed under the EUPL 1.2 or later.
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of Hummingbird DocC Middleware project authors
+//
+// ===----------------------------------------------------------------------===
+
+import protocol ArgumentParser.AsyncParsableCommand
+
+import struct ArgumentParser.OptionGroup
+import struct Logging.Logger
+
+/// A type that implements and runs the sample executable that showcases the `Hummingbird-DocC` middleware.
+@main struct SampleApp {
+    
+    // MARK: Properties
+    
+    /// A type that contains all the necessary input parameters to run the sample executable.
+    @OptionGroup var arguments: Arguments
+
+}
+
+// MARK: - AsyncParsableCommand
+
+extension SampleApp: AsyncParsableCommand {
+    
+    // MARK: Functions
+    
+    func run() async throws {
+        let builder = AppBuilder(logger: {
+            var logger = Logger(label: "sample.hummingbird-docc.logger")
+            
+            logger.logLevel = arguments.logLevel
+            
+            return logger
+        }())
+        
+        let application = builder(arguments)
+
+        try await application.run()
+    }
+    
+}