Let's simplify example integrations with XcodeGen

Swift Package Manager support is around the corner, thanks to @stevenzeck.

With it, we will need to add more Xcode targets to show how to use them. Currently the Test App has four of them, which adds some maintenance load:

I think this also adds confusion for integrators, since the project contains artifacts for a few different types of integration.

Instead, I suggest removing the Xcode project entirely from r2-testapp-swift and instead add one XcodeGen project definition YAML file per integration example.

XcodeGen is a command line tool written in Swift that generates your Xcode project using your folder structure and a project spec. The project spec is a YAML or JSON file that defines your targets, configurations, schemes, custom build settings and many other options.

Pros

Xcode projects are not Git-friendly and it's frequent to have merge issues. Getting rid of it would solve the problem.
The Xcode projects generated by XcodeGen would be simpler and a clearer example of the chosen integration type.

XcodeGen's YAML files are human-readable and in my opinion also a better example on what's needed to integrate Readium than digging into Xcode's build settings.

name: ReadingApp
packages:
  R2Shared:
    url: https://github.com/readium/r2-shared-swift
    from: 2.0.0
  R2Navigator:
    path: ./r2-navigator-swift-local-clone
targets:
  ReadingApp:
    dependencies:
      - package: R2Shared
      - package: R2Navigator

Cons

This requires integrators to install a third-party tool.
- Integrators can always create the project by hand following the YAML file, which should be straightforward even when not familiar with XcodeGen.
XcodeGen might stop being maintained in the future.
- We can always commit again the generated Xcode projects at some point.
- There are similar alternatives.
- This dependency is only for the test app, and not other Readium 2 modules.

One step further

Not related to XcodeGen, but r2-workspace-swift also brings some maintenance load with its 4 different integration branches.

I suggest archiving this repository and instead adding the submodules directly in r2-testapp-swift, when used for development purposes.

Simpler for onboarding, there is a single entry-point repo to check out hosting the documentation.
It better represents the structure of an integrator's reading app, which when using submodules would have them in the app's repo.
We can commit the submodule changes after each PR, making it much easier to pinpoint regressions using git bisect. Right now r2-workspace-swift is only updated after each release, making it not so useful.
- EDIT: To be fair, this is something we could do in r2-workspace-swift too. However, having them in r2-testapp-swift ties any change in the Test App itself to particular commits of the R2 modules.
Users are free to ignore (and not checkout) the submodules when using SPM or Carthage with the test app. The only place where it would show is as empty directories on the file system.

Example generating the test app project using SPM and with LCP:

name: R2TestApp
options:
  bundleIdPrefix: org.readium
packages:
  R2Shared:
    url: https://github.com/readium/r2-shared-swift.git
    branch: develop
  R2Streamer:
    url: https://github.com/readium/r2-streamer-swift.git
    branch: develop
  R2Navigator:
    url: https://github.com/readium/r2-navigator-swift.git
    branch: develop
  ReadiumOPDS:
    url: https://github.com/readium/r2-opds-swift.git
    branch: develop
  ReadiumLCP:
    url: https://github.com/readium/r2-lcp-swift.git
    branch: develop
  Kingfisher:
    url: https://github.com/onevcat/Kingfisher.git
    from: 5.15.8
  MBProgressHUD:
    url: https://github.com/jdg/MBProgressHUD.git
    from: 1.2.0
  SQLite:
    url: https://github.com/stephencelis/SQLite.swift.git
    from: 0.12.2
targets:
  R2TestApp:
    type: application
    platform: iOS
    deploymentTarget: "10.0"
    sources:
      - path: Sources
        excludes:
          - Resources/Samples
      - path: Sources/Resources/Samples
        type: folder
    dependencies:
      - carthage: R2LCPClient
      - package: R2Shared
      - package: R2Streamer
      - package: R2Navigator
      - package: ReadiumOPDS
      - package: ReadiumLCP
      - package: Kingfisher
      - package: MBProgressHUD
      - package: SQLite
    settings:
      OTHER_SWIFT_FLAGS: -DLCP

It generates this project:

readium / swift-toolkit