Allow parameters to be specified through configuration file

[mattt]

As we begin to add (#65) and consider (#57, #72) new options for the generate command, I think it's likely that the number of options for the generate command will soon exceed what can be reasonably expressed through command-line arguments alone.

Maybe this isn't inevitable. If we took seriously the canon of parsimony in our API design, perhaps we'd find that a small, fixed set of parameters are all that are necessary. This could all be a trap, a slippery slope that projects fall into all too frequently in a rush to add functionality. I'd love to be hear better arguments about limiting feature creep.

But from where I am right now, it's hard to look at, say, the configuration options for jazzy or other comparable tools and think that we'll find a way to solve the same problem without a similar number of settings. Taken altogether in aggregate, you start to get the sense about the inherent complexity of the problem.

So, assuming this is indeed something we'll need, it's probably something we should figure out before 1.0.0. Here's what I'm thinking:

• Extend ArgumentParser to make options Codable. Unless this already exists, this is something that would be useful beyond swift-doc and a good candidate for an upstream patch or separate library.
• By default, look for a .swift-doc.json (spelling?) file and read those as a base configuration, and add an option for where to look for a configuration file.
• Options in the configuration file override the default values. Any options passed from the command line to the executable override ones from a configuration file (similar to how most systems work, including UserDefaults).
• We should also think about versioning and validation for these files, as well as documentation.

[kean]

I wonder what happened with the idea of using .swift files as configuration, e.g. .doc.swift. It doesn't seem to be getting high adoption outside of Swift Package Manager. Are you considering this as an option?

[mattt]

There are examples of programming languages working really well for configuration (Homebrew formulas), and there are examples where a programming language would have been preferable (pretty much any configuration system that uses YAML). But I can think of many more examples where using a programming language for configuration eventually required support of a serialized form as well. We saw this with CocoaPods and JSON, and are seeing this now with Swift Package Manager (swift package dump-package).

Holding on Swift Package Manager for a moment: I think there are a few interesting benefits to having a Package.swift file, but they come with serious disadvantages, too. I recently decided to write a new library in preparation for supporting multiple modules for swift-doc. The alternative (how SPM reads the manifest itself) requires Package.swift to be built with special compiler flags and introspected. Reading a JSON file seems pretty nice by comparison.

So yeah, the reason we don't see .swift files for configuration is that very few people know how to do it, and the people who do know better than to try.

[mattt]

See also apple/swift-argument-parser#41