feature: Start at the first non-empty line?

[pawamoy]

Is your feature request related to a problem? Please describe.

Once support for comments in docstrings is implemented, it will still be hard to mark lines or blocks to be removed because that could break parsing of the docstring.

For example:

    """Create and return a warn function.

    <!-- YORE: Bump 1: Remove block. -->
    Parameters:
        name: Deprecated. The logger name.

    Returns:
        A function used to log parsing warnings.
    """

Here the Yore comment would break parsing of the parameters section, because the parser requires that the line above a section is blank.

Describe the solution you'd like

Support having blank lines after a comment? And start only at the first non-blank line?

# YORE: ...

print("...")

"""Summary.

<!-- YORE: ... -->

Parameters:
    ...
"""

Describe alternatives you've considered

Write comments right before their target anyway, and create a Griffe extension to make them blank instead (not removing the line, just emptying it).

Additional context

This suggested solution won't solve the issue that we can't add Yore comments inside sections themselves anyway, so we might be better off creating a Griffe extension 🤔

[pawamoy]

Extension idea tracked here: mkdocstrings/griffe#313