Markdown heading level handling in docstring

[0815Creeper]

Consider docstring:

"""
    foo(x, f, k)

Do stuff

# Arguments
- `x`: some argument
- `f`: some function
    ## Pattern
    - `f(t)`
    - `f(t, u)`
    - `f(t, u, c)`
- `k`: some other argument
"""
function foo(x, f, k)
end

In REPL help, the format is as expected: "Pattern" is indented and a lower level heading as "Arguments"

When making the documentation with Documenter on the other hand, "Pattern" gets translated to <h2> while "Arguements" only becomes <strong>, not <h1>. Therefore it looks quite off.

Using <h1> for "Arguments" is obviously not a good solution either
=> Idea: translate all heading levels in docstrings to <strong> instead of <h_>

[mortenpi]

Yep, we should do this. I assume the issue is that we don't traverse into the AST when doing the h1 -> strong rewrite, and just rewrite top-level elements.

[mortenpi]

I believe the rewriting happens here, if anyone wants to take a stab at PRing this:

Documenter.jl/src/expander_pipeline.jl

Lines 964 to 981 in 6052e5f

	# Convert docstring to MarkdownAST, convert Heading elements, and push to DocsNode
	for (markdown, result) in zip(docstrings, results)
	ast = convert(Node, markdown)
	doc.user.highlightsig && highlightsig!(ast)
	# The following 'for' corresponds to the old dropheaders() function
	for headingnode in ast.children
	headingnode.element isa MarkdownAST.Heading || continue
	boldnode = Node(MarkdownAST.Strong())
	for textnode in collect(headingnode.children)
	push!(boldnode.children, textnode)
	end
	headingnode.element = MarkdownAST.Paragraph()
	push!(headingnode.children, boldnode)
	end
	push!(docsnode.mdasts, ast)
	push!(docsnode.results, result)
	push!(docsnode.metas, markdown.meta)
	end

[odow]

#1146 asks for proper headings in docstrings, so if we decide to fix this, we should probably also close that issue.

[0815Creeper]

About #1146
I would argue, that it is not necessary for "proper headings" to be rendered as part of the docstrings. If this is the prefered option, I assume it would be necessary to format them diffrently than the headings in the rest of the page. Having the # Arguments in every function docstring (part of julias docstring standard, not some optional formating) look the same as the headline of the page would seem out of place. I am neither competent enough in Julia nor in html and CSS to implement such a solution, so if someone else would like to take this, feel free ;) I would still be happy with the bolding of the headings within docstrings