Let plugins add options to `.mdformat.toml` file

[csala]

Context

Currently, mdformat plugins are allowed to implement a add_cli_options function to add arguments to the mdformat ArgumentParser, but there is no way to allow those options to be added to the .mdformat.toml file without monkey patching the mdformat._conf module to add the new options to the DEFAULT_OPTS dictionary or _validate_keys and _validate_values functions.

Proposal

Add a way for plugins to declare acceptable options and values for the mdformat.toml file.

Along the way, maybe also slightly reformat how the options are declared, so that they are not hard-coded in two different places (_conf and _cli) independently. An option for this would be to have them declared only inside _conf, with a way for plugins to alter them, and then have both the _cli.ArgumentParser and the _conf validation functions read and use them.

Tasks and updates

No response

[hukkin]

Thanks for the issue!

Would https://github.com/executablebooks/mdformat/pull/461 work for you? I didn't write any docs yet, but I think the feature is pretty well described by the docstring of the added plugin interface:

def add_cli_argument_group(group: argparse._ArgumentGroup) -> None:
        """Add an argument group to mdformat CLI and add arguments to it.

        Call `group.add_argument()` to add CLI arguments (signature is
        the same as argparse.ArgumentParser.add_argument). Values will be
        stored in a mapping under mdit.options["mdformat"]["plugin"][<plugin_id>]
        where <plugin_id> equals entry point name of the plugin.

        The mapping will be merged with values read from TOML config file
        section [plugin.<plugin_id>].

        (optional)
        """

So with the new endpoint

• plugins' CLI options go to a plugin specific group
• plugins have access to

  [plugin.<plugin_id>]
  some_key = "some value"

  namespace in TOML

• core mdformat merges the CLI values with TOML config

I plan to deprecate the old add_cli_options endpoint as I haven't seen any use case where access to a argparse._ArgumentGroup is not sufficient, and I want to encourage plugins to move their CLI options under a group.

Would these changes break your pyproject plugin?

[csala]

Thanks @hukkin Yes, I think the proposed solution would cover the original request.

WRT to the plugin, I believe that the API change should not break it, but I am not sure if plugin options will be properly picked from the pyproject.toml. I suppose they will, but I will have to test it.

I will give this is a try against your branch to confirm it, and if it breaks I will let you know and try to adapt to it before you release it. Do you have any timeline in mind, to avoid slowing you down?

[hukkin]

I will give this is a try against your branch to confirm it, and if it breaks I will let you know and try to adapt to it before you release it.

That'd be great, thanks!

Do you have any timeline in mind, to avoid slowing you down?

No rush, this can easily wait a month if you're busy.

[hukkin]

I've merged the PR but won't release until you've had the chance to test it, or after a month or so.