Documenter.jl and markdown headings in docstrings

New to Julia
,
1

Apologies as I am new to Julia and still trying to wrap my head around Julia’s documentation style (avoiding argument lists and expected output, etc) and also not allowed to insert links into posts.

The Julia documentation recommends the use of markdown headings in function docstrings (docs.julialang dot org/en/v1/manual/documentation/#Writing-Documentation), but a decision was made in 2023 to remove the semantic meaning of headings and simply parse the heading text to <strong> (issue (github dot com/JuliaDocs/Documenter.jl/issues/2308), PR (github dot com/JuliaDocs/Documenter.jl/pull/2313)).

While this causes no issues in the vast majority of cases, it does mean that:

  1. Nested headings such as
    # Usage

## Arguments
    are flattened into
    <p>
    <strong>Usage</strong>
</p>
<p>
    <strong>Arguments</strong>
</p>
    without preserving the hierarchy or any way to differentiate between the two, even with custom stylesheets, etc.
  2. It seems packages that render documentation into a “printable” format based on Documenter.jl’s AST cannot handle headings in docstrings properly (since they are removed and replaced by strong), which can, for example, lead to the insertion of inappropriate page breaks after headings since they no longer have any special semantic meaning.

Given this design choice, should I be writing docstrings without headings? In the event that a function or module requires more complex documentation, is it the “Julian” way that such documentation must then not be in close proximity to the code but potentially several directories away?

2

This issue is open:

1 Like
3

I saw that, but it is this issue that was ultimately chosen as the solution:

The issue you are linking hasn’t had any activity since 2023, so I assume that the decision is somewhat permanent.