When a reST directive has `has_content` set to `True`, optional
arguments and `final_argument_whitespace` set to True, the presence of a
newline at the start of the directive is significant in communicating
whether specific markup is treated as the argument or content.

    .. banner-1:: This is an argument
       This is still the argument.

       This is content.

    .. banner-2::
       This is still the argument.

       This is content.

    .. banner-3::

       This is content.

       This is more content.

In the above example, `banner-2` and `banner-3` are very similar and
only different in the presence of a newline. This is a subtle failure
mode where written content can end up being silently ignored by the reST
directive due to how arguments vs contents are parsed.

Instead of accommodating for this behaviour by adding additional
complexity to the directive being used, this change stops trying to mix
multiline arguments and content in a single directive by using explicit
options instead. This requires more verbosity but also eliminates this
failure mode entirely.

    .. banner-1::
       :option: This is the option.
                This is still the option.

    .. banner-2::
       This is content.

       This is still content.

    .. banner-3::

       This is content.

       This is still content.

With this change, presence of a newline at the start of the directive is
not determining if specific markup is treated as the argument or
content. This is instead communicated by the presence of the option
syntax which is more explicit and presents proper errors when the syntax
is incorrect.

Co-authored-by: Adam Turner <[email protected]>