Some docstrings still have poor formatting

[malmaud]

Unless I'm doing something wrong, the following functions still have strange formatting when I view their docs (with ?) from the repl:

• count_ones
• count_zeros
• wait
• cholfact!
• println
• rand
• randstring
• randcycle
• exp
• sqrt

[malmaud]

More:

• sinpi
• sinc
• cospi
• cosc
• append!
• push!
• isimmutable
• map
• map!
• ifft
• fieldoffsets
• SymTridiagonal
• lgamma
• mapreduce

[jakebolewski]

That is because these are just RST code blocks not Markdown. Until we transition the manual to Markdown the rendering of these docstrings will be raw RST in the terminal. We could write a pretty printer for RST, but I think effort is better spent to complete the transition.

[malmaud]

That's fair, but is .4 really going to be released with the docs for functions like map and push! just printing raw RST?

[jakebolewski]

Yes, unless someone wants to write a pretty printer. Also, we use RST comments to match the signature so the pretty printer would have to be written specifically for the non-standard RST formatting we are using.

[mbauman]

Is there a list of the syntaxes that are barring their transition to Markdown? Is it possible to work on supporting the unsupported? We'll want to have these things anyways:

• doc-tests (could be fenced codeblocks, e.g., ````jldoctest`)
• manual cross-links (maybe [link text](_rst_anchor) or some other special way of designating an rst anchor)
• function and object cross-references :func:foo`` (maybe splice in $(link(foo))?)

Are there other unsupported syntaxes?

[jakebolewski]

See #12573 and linked issues

[jiahao]

Equations and cross-references are my two big concerns. Citations are a distinct third. Scholarly Markdown is the closest attempt I've seen to address these in an extended Markdown format.