Documentation (#3)

* Add initial documentation

* Add workflow for pushing to GitHub pages

* Fix tmp dir

* fix script issues

* only run on main branch

.github/workflows/documentation.yml

@@ -0,0 +1,39 @@
+name: "Documentation"
+
+on:
+  push:
+    branches:
+    - main
+
+jobs:
+  build:
+    name: Build Documentation
+    runs-on: macos-13
+    env:
+      DEVELOPER_DIR: /Applications/Xcode_15.0.app/Contents/Developer
+      GENERATED_SITE_PATH: "/tmp/_site"
+      HOSTING_BASE_PATH: "https://liamnichols.eu/swift-fixture"
+    steps:
+    - name: Checkout Repo
+      uses: actions/checkout@v3
+    - name: Build Documentation
+      run: swift package --allow-writing-to-directory "${{ env.GENERATED_SITE_PATH }}" generate-documentation --target SwiftFixture --disable-indexing --transform-for-static-hosting --hosting-base-path "${{ env.HOSTING_BASE_PATH }}" --output-path "${{ env.GENERATED_SITE_PATH }}"
+    - name: Upload Site
+      uses: actions/upload-pages-artifact@v1
+      with:
+        path: ${{ env.GENERATED_SITE_PATH }}
+
+  deploy:
+    name: Deploy Documentation
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.github/workflows/tests.yml

@@ -3,10 +3,10 @@ name: "Tests"
 on:
   push:
     branches:
-      - main
+    - main
   pull_request:
     branches:
-      - main
+    - main
 
 jobs:
   macos:

Package.resolved

@@ -1,5 +1,23 @@
 {
   "pins" : [
+    {
+      "identity" : "swift-docc-plugin",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-docc-plugin",
+      "state" : {
+        "revision" : "26ac5758409154cc448d7ab82389c520fa8a8247",
+        "version" : "1.3.0"
+      }
+    },
+    {
+      "identity" : "swift-docc-symbolkit",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-docc-symbolkit",
+      "state" : {
+        "revision" : "b45d1f2ed151d057b54504d653e0da5552844e34",
+        "version" : "1.0.0"
+      }
+    },
     {
       "identity" : "swift-syntax",
       "kind" : "remoteSourceControl",

Package.swift

@@ -8,6 +8,9 @@ let package = Package(
     products: [
         .library(name: "SwiftFixture", targets: ["SwiftFixture"])
     ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.3.0"),
+    ],
     targets: [
         .target(name: "SwiftFixture"),
         .testTarget(name: "SwiftFixtureTests", dependencies: ["SwiftFixture"])

Package@swift-5.9.swift

@@ -12,6 +12,7 @@ let package = Package(
     ],
     dependencies: [
         .package(url: "https://github.com/apple/swift-syntax.git", from: "509.0.0-swift-5.9-DEVELOPMENT-SNAPSHOT-2023-04-25-b"),
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.3.0"),
     ],
     targets: [
         .target(

README.md

@@ -1,5 +1,9 @@
 # SwiftFixture
 
+[![Test Status](https://github.com/liamnichols/swift-fixture/workflows/Tests/badge.svg)](https://github.com/liamnichols/swift-fixture/actions/workflows/tests.yml)
+[![Swift Language Compatibility](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fliamnichols%2Fswift-fixtures%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/liamnichols/swift-fixtures)
+[![Platform Compatibility](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fliamnichols%2Fswift-fixtures%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/liamnichols/swift-fixtures)
+
 SwiftFixture is a tool to help you in writing clean and concise unit tests by standardizing the creation of fixture values.
 
 ## Overview

Sources/SwiftFixture/Documentation.docc/SwiftFixture.md

@@ -0,0 +1,69 @@
+# ``SwiftFixture``
+
+A simple framework for managing test fixtures in Swift.
+
+## Overview
+
+SwiftFixture provides a set of tools designed to help make it easy for you to instantiate and organise values of your own Swift types for use as fixtures during unit testing.
+
+To recap, a [test fixture](https://en.wikipedia.org/wiki/Test_fixture) is an environment used to consistently test our software. For example:
+
+```swift
+struct User {
+    var id: UUID
+    var name: String
+    var createdAt: Date
+    var isActive: Bool
+    // ...
+}
+
+class SummaryTests: XCTestCase {
+    func testSummaryForActiveUser() {
+        let user = User(id: UUID(), name: "John", createdAt: Date(), isActive: true)
+
+        let actual = getSummary(for: user)
+        let expected = "John is currently active"
+
+        XCTAssertEqual(actual, expected)
+    }
+}
+```
+
+In the `testSummaryForActiveUser()` example above, the `user` property is our test fixture that we rely on to test the behaviour of the `getSummary(for:)` method. Using the existing `User` initializer directly to create the fixture works, but over time you might start running into issues as your codebase matures. 
+
+For example, you might already have noticed that the test is forced to reference the unused `id` and `createdAt` arguments. Additionally, if this practice was applied in multiple places, adding a new argument to the `User` initializer would require a large number of code changes across your tests, or worse, you could find yourself taking shortcuts with default values when you don't want to be. 
+
+SwiftFixture aims to help provide a structure for creating fixtures that can scale with your codebase as it grows:
+
+```swift
+class SummaryTests: XCTestCase {
+    let fixture = Fixture()
+
+    func testSummaryForActiveUser() throws {
+        var user = try fixture(User.self)
+        user.isActive = true
+
+        let actual = getSummary(for: user)
+        let expected = "\(user.name) is currently active"
+
+        XCTAssertEqual(actual, expected)
+    }
+}
+```
+
+
+## Topics
+
+### Basics
+
+- ``Fixture``
+
+### Registering Custom Types 
+
+- ``FixtureProviding``
+- ``ProvideFixture()``
+
+### Misc
+
+- ``PreferredFormat``
+- ``ResolutionError``

Sources/SwiftFixture/Fixture.swift

@@ -62,7 +62,7 @@ open class Fixture {
 
     /// Creates a fixture instance with builtin fixture types using the preferred format provided.
     ///
-    /// - Parameter preferredFormat: The preferred format used when vending fixture values. Defaults to ``PreferredFormat.random``.
+    /// - Parameter preferredFormat: The preferred format used when vending fixture values. Defaults to ``PreferredFormat/random``.
     public init(preferredFormat: PreferredFormat = .random) {
         registerDefaults(using: preferredFormat)
     }