Allow configuration to be read from pyproject.toml (as an alternative to mkdocs.yml)

[mcarans]

Thanks for your work on this project. I have a suggestion: it would be great if the configuration could be read from pyproject.toml as an alternative to having a separate file mkdocs.yml since pyproject.toml has become the standard place for Python configuration.

[pawamoy]

Cons:

• MkDocs is language agnostic, while pyproject.toml is specific to Python projects.
• The configuration is currently written in YAML, with specific features (environment variables, YAML tags, etc.) that are not translatable to TOML.

[mcarans]

The idea would be that pyproject.toml would be offered as an alternative for Python developers with mkdocs.yml still usable. These days, my tool selection is driven in part by whether the tool supports configuration in pyproject.toml as looking after tool configurations in multiple places across multiple projects is inconvenient.

I suggest something simple eg.

[tool.mkdocs]
config = """
YAML config here
"""

This is similar to how tox handles being configured from pyproject.toml without needing an alternate format (in tox's case, it uses ini format).

[pawamoy]

I was advocating for putting everything in pyproject.toml before, but eventually prefer putting each tool's config into its own file, all in a config folder, because otherwise pyproject.toml grows too big and unreadable.

The issue with putting YAML config in a TOML string is that you lose all support for YAML in your IDE: auto-formatting, validation, auto-completion, etc. I'm not sure that would be a good UX for MkDocs users. I don't have a strong opinion on this though.

[mcarans]

@pawamoy I agree it would be good if tools allowed specifying that their configuration come from a specific subfolder, but is that possible for most of the tools you use? I had thought that most (such as tox by the look of it) expect that their configuration file be in the root folder or sometimes in their own specific subfolder rather than allowing you to specify.

[pawamoy]

They all provide an option to specify the path to the config file to use. I set these options in my task runner config (or makefile), so that I don't have to type it every time :)

[pawamoy]

Related: https://github.com/dot-config/dot-config.github.io 🙂

[oprypin]

Sorry, this will not be done.

MkDocs is its own application, not a development tool for Python projects.

The rest what @pawamoy already said, I agree