Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documenter.mdparse(md; mode=:single) unexpectedly returns list #2253

Open
goerz opened this issue Sep 13, 2023 · 2 comments
Open

Documenter.mdparse(md; mode=:single) unexpectedly returns list #2253

goerz opened this issue Sep 13, 2023 · 2 comments
Assignees

Comments

@goerz
Copy link
Member

goerz commented Sep 13, 2023

Maybe I'm just misreading the documentation for Documenter.mdparse where it says that ":single (default) – returns a single block-level object", but I'm finding the function to return a single-element list:

using Documenter  # master
using MarkdownAST
using Test

MD_MINIMAL = raw"""
Text with [rabiner_tutorial_1989](@cite).
"""

@testset "Documenter.mdparse" begin
    minimal_block_ast = MarkdownAST.@ast MarkdownAST.Paragraph() do
        MarkdownAST.Text("Text with ")
        MarkdownAST.Link("@cite", "") do
            MarkdownAST.Text("rabiner")
            MarkdownAST.Emph() do
                MarkdownAST.Text("tutorial")
            end
            MarkdownAST.Text("1989")
        end
        MarkdownAST.Text(".")
    end
    @test_broken Documenter.mdparse(MD_MINIMAL; mode=:single) == minimal_block_ast
    @test Documenter.mdparse(MD_MINIMAL; mode=:single) == [minimal_block_ast] # XXX
    @test Documenter.mdparse(MD_MINIMAL; mode=:blocks) == [minimal_block_ast]
    @test Documenter.mdparse(MD_MINIMAL; mode=:span) == [minimal_block_ast.children...]
end

For markdown with multiple blocks, :single throws an error (as documented).

In principle, it would make the most sense to me if mode=:single were to return the Paragraph() node directly. On the other hand, I suppose always returning a list is more type stable. But then the documentation should be changed.

I might want to use mdparse with mode=:single in DocumenterCitations, so it would be good to clarify what the intended interface is.

@goerz
Copy link
Member Author

goerz commented Sep 13, 2023

Oh, I just realized the function is indeed annotated as returning Vector{MarkdownAST.Node{Nothing}}. So this must be intentional, for type stability.

I'll assume it will stay that way, then (but maybe I'll submit a tiny PR to update the documentation).

@mortenpi
Copy link
Member

To be honest, I don't remember why it works now the way it does, and this is very much an internal function. Probably for consistency, yes. But I did apparently forget to fully updated the docstring, so a PR to bring the up to speed with reality is always welcome.

@goerz goerz self-assigned this Nov 8, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants