Add a configuration file (`pdoc.toml`)

[clbarnes]

Problem Description

Most commonly, people will be using the same set of arguments every time they build their documentation. While this could be delegated to a task runner like Make or Just, it would also be convenient for pdoc to define its own config file and read arguments from that.

Proposal

• Define a config file name, format, and spec, e.g. pdoc.toml, which can represent any arguments which can be passed to the CLI.
• When pdoc is called, check for this config file in the working directory (possibly also its ancestors).
• Merge the commnd line and config arguments.
• Add a --config argument for overriding the config location (do not allow this to be configured in pdoc.toml).

Alternatives

Keep the status quo, encouraging people to use their own collection of scripts and config scattered across build tools and contexts.

Bikeshedding file formats:

• no YAML
• Why JSON isn't a good configuration language
• INI is not real
• TOML is simple, looks nice for flat config, is part of the core python packaging spec
• nothing else is nearly as popular as the above

Pain points

• merging config can be non-trivial where arguments can be repeated, e.g. the module list - do you extend or replace?
• resolving relative paths may need to work differently in the CLI (relative to working directory) and the config file (relative to the directory of the config file)

Example

# module, path, and regex ignore patterns could be split into different keys
modules = ["pdoc.doc", "./pdoc/doc.py", "!foo.bar"]

output_directory = "./build/"
docformat = "markdown"
include_undocumented = true
edit_url = {
  "module.name" = "https://my_prefix.com/"
}

...