Cannot build docs from podspec with unpublished dependency pod

[mludowise-stripe]

We have multiple cocoapods in our repository called Stripe and StripeCore. The Stripe pod depends on the StripeCore pod of the same version (e.g. [email protected] depends on [email protected]).

When we deploy a new version of our pod, our deployment process is to:

1. Bump our podspec version numbers
2. Generate docs using Jazzy
3. Merge the updated podspec & docs to our repo & tag the commit
4. pod trunk push StripeCore
5. pod trunk push Stripe

When we generate our docs, the current version of our StripeCore pod is not yet published. So Jazzy produces something like the following error (in this example, the version is 100.0.0):

[!] CocoaPods could not find compatible versions for pod "StripeCore": (Pod::NoSpecFoundError)
  In Podfile:
    Stripe (from `/Users/mludowise/stripe/stripe-ios-private`) was resolved to 100.0.0, which depends on
      StripeCore (= 100.0.0)

None of your spec sources contain a spec satisfying the dependency: `StripeCore (= 100.0.0)`.

You have either:
 * out-of-date source repos which you can update with `pod repo update` or with `pod install --repo-update`.
 * mistyped the name or version.
 * not added the source repo that hosts the Podspec to your Podfile.

Steps to reproduce:

1. git clone [email protected]:stripe/stripe-ios.git && cd stripe-ios && checkout origin/mludowise/pod_dependency_jazzy_example
   • I bumped the podspec version in this branch to 100.0.0 since that won't be published to CP any time soon
2. jazzy --config .jazzy.yaml --github-file-prefix "https://github.com/stripe/stripe-ios/tree/100.0.0" --podspec Stripe.podspec

This is the git branch with the example: https://github.com/stripe/stripe-ios/tree/mludowise/pod_dependency_jazzy_example

Proposal

Ideally, there would be a way to specify to Jazzy a list of local .podspec files to use as dependencies rather than fetching from pod trunk. Perhaps something like:

jazzy --podspec Stripe.podspec --include-podspecs StripeCore.podspec,/path/to/AnotherPod.podspec,...

The resulting podspec files could be included in the generated podfile inside podspecdocumenter.rb like:

pod 'MyPod', path: '/path/to/mypod/'
pod 'DependencyPod', path: '/path/to/dependencypod/'

Cocoapods uses an --include-podspecs flag as an option for pod lib lint to lint against local podspec files, so there's precedence for the name.

Workaround

For anyone else running into this issue, we devised a workaround for the dependency issue by creating a local git spec repo that contains .podspec files for our dependency pods with file:// URLs for their s.source value. Then we pass that generated spec repo to jazzy using the --pod-sources option. It's certainly not ideal, but it seems to function for the time being.

• Script for creating a temp spec repo: https://github.com/stripe/stripe-ios/blob/mludowise/pod_dependency_jazzy_example/ci_scripts/make_temp_spec_repo.sh
• Used by our docs generation here: https://github.com/stripe/stripe-ios/blob/mludowise/pod_dependency_jazzy_example/ci_scripts/build_documentation.sh#L49
  To

[johnfairh]

#650, #1172 for the previous 'add things from pod lib lint'.