Example of how to use hfun, retrieve & display docstrings a-la Documenter

[tlienart]

function hfun_doc(params)
    fname = params[1]
    doc = eval(Meta.parse("@doc $fname"))
    txt = Markdown.plain(doc)
    split = match(r"^```((?:.|\n)*?)```((?:.|\n)*)$", txt)
    head = split.captures[1]
    # convert body from markdown to html
    body = Markdown.html(Markdown.parse(split.captures[2]))
    # possibly further processing here
    h = IOBuffer()
    write(h, """
        <div class="docstring header">$head</div>
        <div class="docstring content">$body</div>
        """)
    return String(take!(h))
end

(example worked through with @shashi )

What they actually use: https://github.com/JuliaSymbolics/SymbolicUtils.jl/blob/website/utils.jl
How it looks: https://juliasymbolics.github.io/SymbolicUtils.jl/api/

[newptcai]

Would be nice to add this to the document.

[newptcai]

Where is hfun described in the document?

This page is empty https://franklinjl.org/syntax/utils/

[tlienart]

Yes this is "todo" there is info there: https://github.com/tlienart/Franklin.jl/blob/master/NEWS.md

[newptcai]

Once I get

doc = eval(Meta.parse("@doc $fname"))

Is there anyway to actually parse it with Franklin as if it were written in a plain md file?

Basically I have an example in the docstring that I want to run and show the result on a web page.

[shashi]

Is there anyway to actually parse it with Franklin as if it were written in a plain md file?

you can use fd2html, I have to move to that too.

[newptcai]

@shashi Thanks I tried it like this

using Markdown, Franklin

function hfun_doc(params)
    fname = params[1]
    head = length(params) > 1 ? params[2] : fname
    type = length(params) == 3 ? params[3] : ""
    doc = eval(Meta.parse("using PlaneGeometry; @doc PlaneGeometry.$fname"))
    txt = Markdown.plain(doc)
    # possibly further processing here
    #body = Markdown.html(Markdown.parse(txt))
    body = fd2html(txt)
    return """
      <div class="docstring">
          <h2 class="doc-header" id="$fname">
            <a href="#$fname">$head</a>
            <div class="doc-type">$type</div></h2>
          <div class="doc-content">$body</div>
      </div>
    """
end

It does not work though. Do you have a working example. (The code snippet is from you.)

[tlienart]

Please use fd2html(text, internal=true)

I need to show good examples of this and sorry this wasn’t done yet and that the experience is not very smooth yet... I just haven’t had the time :/

[VarLad]

@tlienart Does this mean we can use Franklin to generate the docs via docstrings?

[tlienart]

@VarLad yes, though there is no specific function to help you do this. Basically whatever logic you can think of that can be coded in Julia and outputs HTML is game. So in particular you could even call documenter's internal functions if that was helpful to your purpose.

This has been done before (I need to find the link again, it's one of the Julia symbolics packages) but, again, this is a path where you have to code stuff yourself.

Now let's say you find a path that you like a lot and think that other users could make use of it, we could either bake that into Franklin or you could create a package that people could call that would define a few useful "hfuns" that people can import :)

I hope this makes sense!