doxy/README.md

<p align="center">
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://github.com/hummingbird-project/hummingbird/assets/9382567/48de534f-8301-44bd-b117-dfb614909efd">
  <img src="https://github.com/hummingbird-project/hummingbird/assets/9382567/e371ead8-7ca1-43e3-8077-61d8b5eab879">
</picture>
</p>

#  Doxy

This is a server-side service that proxies requests to any [DocC](https://www.swift.org/documentation/docc/) archive available at a certain folder in the local machine.

This application was written with the [Swift programming language](https://www.swift.org), and it was built on top of the [Hummingbird](https://wwww.hummingbird.codes) framework.

### Requirements

This application requires that the [Swift v6](https://www.swift.org/blog/announcing-swift-6/) compiler is installed in the local machine. In principle, the service should be able to run on *MacOS*, *Linux*, and even *iOS* platforms. 

Furthermore, the [Git](https://git-scm.com) source control management software is also required to clone this repository into a local machine somehow. 

With these pieces of software installed, then it would be certainly possible for this service to be downloaded (or cloned) and installed locally.

In case it is desirable to use the [Docker](https://www.docker.com) container solution, then it is also recommandable to have this software installed into the local machine, as the building tool of the service supports it.

### Dependencies

This service depends on the following [SPM](https://www.swift.org/documentation/package-manager/) libraries and plugins to be compiled and built, before installing it locally: 

* [Hummingbird library](https://github.com/hummingbird-project/hummingbird)
* [Swift Argument Parser library](https://github.com/apple/swift-argument-parser)
* [Swift DocC plugin](https://github.com/swiftlang/swift-docc-plugin)

### Installation

To install this service, please do execute the following commands in the prompt of the **Terminal** command-line app in the local system:

```bash
# Clone the repository into a chosen folder within the local file system.
$ git clone https://repo.rock-n-code.com/rock-n-code/doxy.git .
# Change folder to the recently cloned repository.
$ cd doxy
# Execute the `install` target from the `Makefile` file.
$ make install
# Make sure the service has been installed in the local machine.
$ doxy --help
```

### Usage

To use this service, please do execute the following commands in the prompt of the **Terminal** command-line app in the local system:

```bash
# Execute the service with a path to DocC archives in the local file system.
$ doxy --archive-path path/to/docc/archives
```

The other input parameters have defined some default values already. In case it is required to use other values than those defined by default, please do refer to the service's documentation also in the prompt of the **Terminal** command-line app:

```bash
# List all the input parameters supported by the service.
$ doxy --help
```

### Documentation

For more detailed explanations about any of the types on either the *App* and the *Library* targets, which together compose the service, then it is possible to generate the respective [DocC](https://www.swift.org/documentation/docc/) archives inside a provided archives folder in the local file system by executing the following command in the prompt of the **Terminal** command-line app:

```bash
# Generate DocC archives related to the App and the Library packages of the service.
$ make build-doc
```

### Other available features

Given this service might also provide other useful *development/management/container*, functionalities, please refer to the available targets provided by the `Makefile` by running the following command in the prompt of the **Terminal** command-line app:

```bash
# List all the possible targets provided by the Makefile file.
$ make
```