Repository navigation
Add a configuration file (pdoc.toml) #878
Description
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
pdocis called, check for this config file in the working directory (possibly also its ancestors). - Merge the commnd line and config arguments.
- Add a
--configargument for overriding the config location (do not allow this to be configured inpdoc.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/"
}
...
Activity
jacobwilliams commentedon Apr 10, 2026
It would be better to put this in the
pyproject.toml, which can be used to put settings for other tools.mhils commentedon Apr 10, 2026
I like that alternative. What's wrong with
pdoc.shthat just contains a pdoc invocation? I appreciate you sending #879, but that PR adds extra complexity for the user and 400 lines I don't want to maintain.clbarnes commentedon Apr 10, 2026
I agree that it adds complexity in terms of the space of things they can possibly include in their repo, but I believe that it significantly simplifies most usage by most users by introducing an opinionated canonical location for this kind of configuration.
With this config file in place, you set it once when you start using pdoc, and never think about it again; new contributors never have to think about it at all. Without the config file, you have to remember, and new contributors have to learn, whether they add the config themselves, whether they have to dig around in the repo to find a script which has the arguments set up (maybe multiple scripts for different development environments), whether they have to invoke it through some task runner, whether CI is doing it the same way, and so on.
Of course it's your prerogative re. the maintenance burden; if there's anything I can do to trim some fat and make it less burdensome I'm open to feedback (e.g. only supporting it in pyproject.toml, defining the CLI defaults in the Config object to avoid the
or_elselogic in__main__, cutting down the docstrings and number of constructors for Config etc.).mhils commentedon Apr 10, 2026
Let me think about this for a bit. A minimal version that only accepts pyproject.toml may make sense, I don't think the current state is terrible though.
clbarnes commentedon Apr 10, 2026
FWIW python 3.10 doesn't have TOML support built-in so it would mean bringing in tomli. As we'd be configuring for tomli anyway, I would suggest depending on a recent version and just using tomli until TOML 1.1 hits stdlib (probably python 3.15; already merged). Mainly TOML 1.1 means you can use multiline tables and arrays, which makes the modules list and edit-url mappings look nicer. But I can also see an argument for only relying on tomli for python 3.10 so we can drop the dependency in a few months when 3.10 goes EOL.