Repository navigation
Add a configuration file (pdoc.toml) #878
Description
Activity
It would be better to put this in the
pyproject.toml, which can be used to put settings for other tools.Reacted by Chris Barnes and Connor WilloughbyI 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.).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.
Reacted by Chris BarnesFWIW 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.
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
pdoc.toml, which can represent any arguments which can be passed to the CLI.pdocis called, check for this config file in the working directory (possibly also its ancestors).--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:
Pain points
Example