main branch/v2.1.0 apparently no longer accepts a single extract block

[Glen Whitney]

I am trying to update the mkdocs-semiliterate plugin built on mkdocs-simple to v2.1.0 and/or to the main branch (as you may recall, I prefer the plugin to itself explicitly extract from other files when producing documentation, rather than having the processing of those other files result in the creation of "snippet" files by side effect which are then included in the produced documentation by another mechanism -- hence I published mkdocs-semiliterate).

However, some of my tests now fail with

ERROR    -  Config value: 'plugins'. Error: Plugin 'semiliterate' value:
            'semiliterate'. Error: Sub-option 'extract' configuration error:
            Expected a list of items, but a <class 'dict'> was given.

The relevant section of an mkdocs.yml where this happens is

    semiliterate:
      - pattern: '\.py$'
        extract: {start: '"""\smd', stop: '"""'}
      - pattern: '.drone.yml'
        destination: 'drone_develop.md'
        extract:
          start: '### develop'
          stop: '^\s*###'
          replace: ['^# (.*\s*)$', '^\s*-(.*\s*)$']

(As you can see, each of these file patterns has just one extract block.)
The documentation for v2.1.0 still claims that a single block rather than a list of blocks is permitted, and there is still a line of code in the class Semiliterate constructor to handle this:

        if isinstance(extract, dict):
            # if there is only one extraction pattern, allow it to be a single
            # dict entry
            extract = [extract]

but I believe the new more-elaborated configuration schema for the plugin is causing mkdocs to reject semiliterate parameters with just one block rather than a list of them before the Semiliterate code ever gets to processing the extract parameter, cf. lines 181-190 of plugin.py:

    # #### extract
    #
    # This parameter determines what will be extracted from a scanned
    # file that matches the pattern above. Its value should be a block
    # or list of blocks of settings.
    #
    # {% include "mkdocs_simple_plugin/extract_config.snippet" %}
    extract = config_options.Optional(config_options.ListOfItems(
        config_options.SubConfig(ExtractConfig)))
    #

I don't think the config schema in the code actually allows for both the "block or list of blocks" possibilities in the doc comments just above the code.

Would you like me to try to generate a PR to restore accepting just a block of settings rather than a list of them? Or do you prefer to handle this yourself?

[Allison Thackston]

If you could write an integration test, that would be great. I can revert the commit until I can make the new options work.

[Glen Whitney]

Oh, I mean, it doesn't affect mkdocs-semiliterate until I actually update the mkdocs-simple-plugin dependency that it calls for. I just like to try to stay at the latest. My point is, it's not really necessary to revert; I can just wait to update. But in any case, I will go ahead and file a test-only PR on top of current main to add a test for the mkdocs.yml I use in mkdocs-semiliterate.

[Glen Whitney]

OK, #405 is passing on main where I see you did revert the new config scheme (sorry about the trouble) and it fails in 2.1.0, so that should provide a test to ensure that the single-block possibility for the extract option is preserved. As ever, thanks for the effort you put into mkdocs-simple-plugin.

[Allison Thackston]

Thanks!