From cb0a4d20bb1deeb6c6f874e721635164356be807 Mon Sep 17 00:00:00 2001 From: Adam Young Date: Wed, 17 Jan 2024 14:12:07 +0000 Subject: [PATCH] DOCS: Development (#141) * DOCS: Development * WIP * WIP * WIP * Fix typo --- .github/workflows/lint.yml | 23 +++++++-- .gitignore | 1 + Dockerfile | 9 ---- Makefile | 100 +++++++++++++++++++++++++++++++++++-- README.md | 80 +++++++++++++++++++++++++++++ 5 files changed, 197 insertions(+), 16 deletions(-) delete mode 100644 Dockerfile diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 8babe4ba..1b49f706 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -26,7 +26,7 @@ jobs: - name: Swiftlint run: swiftlint --strict --reporter github-actions-logging - swiftformt: + swiftformat: name: SwiftFormat runs-on: ubuntu-latest container: @@ -37,16 +37,31 @@ jobs: - name: SwiftFormat run: swiftformat --lint . - + markdownlint: name: Markdownlint runs-on: ubuntu-latest + container: + image: docker://ghcr.io/igorshubovych/markdownlint-cli:latest steps: - name: Checkout uses: actions/checkout@v4 - name: Lint README - run: docker run -v $PWD:/workdir ghcr.io/igorshubovych/markdownlint-cli:latest "README.md" + run: markdownlint "README.md" - name: Lint DocC files - run: docker run -v $PWD:/workdir ghcr.io/igorshubovych/markdownlint-cli:latest "**/*.docc/**/*.md" + run: markdownlint "**/*.docc/**/*.md" + + # markdownlint: + # name: Markdownlint + # runs-on: ubuntu-latest + # steps: + # - name: Checkout + # uses: actions/checkout@v4 + + # - name: Lint README + # run: docker run --rm -v $PWD:/workdir ghcr.io/igorshubovych/markdownlint-cli:latest "README.md" + + # - name: Lint DocC files + # run: docker run --rm -v $PWD:/workdir ghcr.io/igorshubovych/markdownlint-cli:latest "**/*.docc/**/*.md" diff --git a/.gitignore b/.gitignore index c111f612..efc63d83 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ xcuserdata/ .vscode *.xctestplan +docs/ diff --git a/Dockerfile b/Dockerfile deleted file mode 100644 index ec419a13..00000000 --- a/Dockerfile +++ /dev/null @@ -1,9 +0,0 @@ -FROM swift:5.9.2-jammy - -WORKDIR /tmp - -ADD Sources ./Sources -ADD Tests ./Tests -ADD Package.swift ./ - -CMD swift build --build-tests && swift test --skip-build --filter TMDbTests diff --git a/Makefile b/Makefile index 68162e96..bef5e8d8 100644 --- a/Makefile +++ b/Makefile @@ -1,3 +1,97 @@ -linuxtest: - docker build -f Dockerfile -t linuxtest . - docker run linuxtest +TARGET = TMDb +TEST_TARGET = TMDbTests +INTEGRATION_TEST_TARGET = TMDbIntegrationTests + +IOS_DESTINATION = 'platform=iOS Simulator,name=iPhone 15,OS=17.2' +WATCHOS_DESINTATION = 'platform=watchOS Simulator,name=Apple Watch Series 9 (45mm),OS=10.2' +TVOS_DESTINATION = 'platform=tvOS Simulator,name=Apple TV 4K (3rd generation),OS=17.2' + +SWIFT_CONTAINER_IMAGE = swift:5.9.2-jammy + +.PHONY: clean +clean: + swift package clean + rm -rf docs + +.PHONY: format + swiftlint --fix + swiftformat . + +.PHONY: lint +lint: + swiftlint --strict + swiftformat --lint . + +.PHONY: lint-markdown +lint-markdown: + markdownlint "README.md" + markdownlint "**/*.docc/**/*.md" + +.PHONY: build +build: + swift build + +.PHONY: build-linux +build-linux: + docker run --rm -v "$${PWD}:/workspace" -w /workspace $(SWIFT_CONTAINER_IMAGE) /bin/bash -cl "swift build -Xswiftc -warnings-as-errors" + +.PHONY: build-release +build-release: + swift build -c release -Xswiftc -warnings-as-errors + +.PHONY: build-linux-release +build-linux-release: + docker run --rm -v "$${PWD}:/workspace" -w /workspace $(SWIFT_CONTAINER_IMAGE) /bin/bash -cl "swift build -c release -Xswiftc -warnings-as-errors" + +.PHONY: build-docs +build-docs: + SWIFTCI_DOCC=1 swift package generate-documentation --product $(TARGET) + swift package resolve + +.PHONY: docs +preview-docs: + SWIFTCI_DOCC=1 swift package --disable-sandbox preview-documentation --target $(TARGET) + +.PHONY: generate-docs +generate-docs: + SWIFTCI_DOCC=1 swift package --allow-writing-to-directory docs \ + generate-documentation --target $(TARGET) \ + --disable-indexing \ + --transform-for-static-hosting \ + --hosting-base-path $(TARGET) \ + --output-path docs + +.PHONY: test +test: + swift build -Xswiftc -warnings-as-errors --build-tests + swift test --skip-build --filter $(TEST_TARGET) + +.PHONY: test-ios +test-ios: + xcodebuild build-for-testing -scheme $(TARGET) -only-testing $(TEST_TARGET) -destination $(IOS_DESTINATION) + xcodebuild test-without-building -scheme $(TARGET) -only-testing $(TEST_TARGET) -destination $(IOS_DESTINATION) + +.PHONY: test-watchos +test-watchos: + xcodebuild build-for-testing -scheme $(TARGET) -only-testing $(TEST_TARGET) -destination $(WATCHOS_DESINTATION) + xcodebuild test-without-building -scheme $(TARGET) -only-testing $(TEST_TARGET) -destination $(WATCHOS_DESINTATION) + +.PHONY: test-tvos +test-tvos: + xcodebuild build-for-testing -scheme $(TARGET) -only-testing $(TEST_TARGET) -destination $(TVOS_DESTINATION) + xcodebuild test-without-building -scheme $(TARGET) -only-testing $(TEST_TARGET) -destination $(TVOS_DESTINATION) + +.PHONY: test-linux +test-linux: + docker run --rm -v "$${PWD}:/workspace" -w /workspace $(SWIFT_CONTAINER_IMAGE) /bin/bash -cl "swift build -Xswiftc -warnings-as-errors --build-tests && swift test --skip-build --filter $(TEST_TARGET)" + +.PHONY: integration-test +integration-test: .check-env-vars + swift build --build-tests + swift test --skip-build --filter $(INTEGRATION_TEST_TARGET) + +.PHONY: ci +ci: .check-env-vars lint lint-markdown test test-ios test-watchos test-tvos test-linux integration-test build-release build-docs + +.check-env-vars: + @test $${TMDB_API_KEY?Please set environment variable TMDB_API_KEY} diff --git a/README.md b/README.md index 09ca8ae1..d875b2a2 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,86 @@ Create an API key from The Movie Database web site Documentation and examples of usage can be found at [https://adamayoung.github.io/TMDb/documentation/tmdb/](https://adamayoung.github.io/TMDb/documentation/tmdb/) +## Development + +### Prerequisites + +Install [homebrew](https://brew.sh) and the follow formulae + +* swiftlint +* swiftformat +* markdownlint + +```bash +brew install swiftlint swiftformat markdownlint +``` + +### Before submitting a PR + +#### Unit and Integration Tests + +Ensure all new code is covered by unit tests. If any new methods are added to +services that make calls to TMDb API endpoints, ensure there are integration tests +covering these. + +#### Coding Style + +Coding style is enforced by `swiftlint` and `swiftformat`. + +Use the following command to lint the codebase: + +```bash +make lint +``` + +To format the codebase use: + +```bash +make format +``` + +#### DocC Documentation + +Ensure all `public` classes, structs, properties and methods are commented + +The DocC documentation can be built and hosted locally by + +```bash +make preview-docs +``` + +See [DocC | Apple Developer Documentation](https://developer.apple.com/documentation/docc) +for more details. + +#### CI Checks + +Before submitting a PR, ensure all CI checks will pass: + +```bash +make ci +``` + +CI checks are made up of the follow tasks: + +```bash +make lint +make lint-markddown +make test +make test-ios +make test-watchos +make test-tvos +make test-linux +make integration-test +make build-release +make build-docs +``` + +In order to run integration tests the `TMDB_API_KEY` environment variable needs +to be set. + +Running unit tests on Linux requires [Docker](https://www.docker.com) to be +running. + ## References * [https://www.themoviedb.org](https://www.themoviedb.org)