Using Documenter.jl for non-Julia package documentation

General Usage
2

I’m not sure how hackable Documenter.jl is for this kind of stuff; Franklin on the other hand (since you mentioned it) is as hackable as you want but it would require some effort. On the top of my head the key thing would be to write your own scraper (in Julia) to retrieve docstrings & function signatures from your codebase (that should not be too hard) and then you can just plug the results in a page.

Here’s a very simple POC, let’s say you have this in file.cpp

/**
 * Takes two integers and sums them
 */
int sum(int a, int b) {
   int c = a+b;
   return c;
}

/**
 * Takes two integers and subtracts them
 */
int sub(int a, int b) {
   int c = a-b;
   return c;
}

A poor man’s parser is to look for a /** at the start of a line then capture until */

function poor_parser(s)
    lines = split(s, '\n')
    docstrings = String[]
    open = false
    curds = ""
    for line in lines
        startswith(line, "/**") && (open = true)
        if open
            curds *= line * "\n"
            if endswith(line, "*/")
                push!(docstrings, strip(curds))
                curds = ""
                open = false
            end
        end
    end
    return docstrings
end

You can paste that function in a utils.jl file of a Franklin folder adding at the bottom

function hfun_docstring(args)
    r = ""
    for ds in poor_parser(read(args[1], String))
      r *= "<pre><code>$ds</code></pre>"
    end
    return r
end

You can then call that on a page with {{docstring path/file.cpp}}

Here’s what it looks like: Franklin Sandbox
Here’s the source: GitHub - tlienart/cppds

Of course this might not be the shortest path to what you want :joy: . Also in practice you’d want to capture the line after the docstring, do some further processing etc etc which may be more effort than you’d like.

PS: I didn’t explain everything in details because this may be far from what you’re looking for; should you be interested, feel free to reach out on Slack or open a GitHub issue.

4 Likes