Support newline between autodoc identifer and YAML options

[Archmonger]

The current syntax of ...

::: my_package.my_module.MyClass
    handler: python
    options:
      members:
        - method_a
        - method_b
      show_root_heading: false
      show_source: false

... does not play well with markdown formatters.

Consider changing the syntax. Here's some ideas.

A markdown list, in conjunction with a flag variable

::: my_package.my_module.MyClass has_options=true

    - handler: python
    - options
      - members
        - method_a
        - method_b
      - show_root_heading: false
      - show_source: false

A markdown list, with an indicator flag

::: my_package.my_module.MyClass

    - #!mkdocstrings
    - handler: python
    - options
      - members
        - method_a
        - method_b
      - show_root_heading: false
      - show_source: false

[pawamoy]

Hello, thanks for the suggestion. We will probably not change the syntax any time soon. Have you tried:

::: my_package.my_module.MyClass

    handler: python
    options:
      members:
        - method_a
        - method_b
      show_root_heading: false
      show_source: false

?

That would make the YAML options equivalent to a code block, which would then not be re-formatted by tools, and would fallback gracefully when displaying in GitHub or else. If it does not work, I'm OK for us to bring support.

[Archmonger]

That seems to work for preventing markdown formatters from breaking the syntax.

However, mkdocstrings no longer parses it as configuration values.

[pawamoy]

I see, thank you for trying. Let's make it work then.

[pawamoy]

This will be released in the next version 🙂