Don't generate headings about docstringextensions.jl HOT 2 CLOSED

It would allow more freedom in how the abbreviations can be integrated into docstrings.

The problem with that of course is that different packages might start using different naming schemes, such as Arguments vs Args vs Parameters. I'm not totally against the idea, though it should be kept in mind if we decide to leave out headers.

I think according to the manual the idiomatic way to write docstrings is to have the signature code blocks as the first thing in the docstring, and there we definitely don't need the heading

That convention is only due to genstdlib.jl and the RST manual needing to find docstrings based on their first code block. It's only idiomatic by necessity really. Once we get the manual moved over to markdown I think it would be best to begin revisiting the current conventions. For example, starting a docstring with a short one line paragraph describing the object may be better in some cases than launching directly into the signature. It very much depends on what's being documented I think.

I would propose changing the semantics so that the abbreviation would generate only the list/block/etc. and would not decorate it.

Perhaps we could have it both ways and allow abbreviations to "turn off" the header if needed. Something like:

"""
$(SIGNATURE)
# Fields

$(!FIELDS)
"""

where we add a Bool field to the Abbreviation subtypes and define ! to negate it. I think we'd need to actually test that out to see whether it's not too complex/confusing.

Another thing that could potentially help us is a docstirng linting package (DocStringLinter.jl probably) that checks whether docstrings are being written in accordance with the guidelines we end up settling on, whatever they may be.

from docstringextensions.jl.

Having scanned over some of the HTML docs that have "Signature" headers it does look quite verbose, so I think this probably is a worthwhile change to make. As you say, we can manually add a header when actually needed.

from docstringextensions.jl.