Documenter.jl: Option to include source code in each docstring

[cadojo]

Does anyone know the best way to include source code in Markdown / PDF documents produced by Documenter.jl?

Recently, I've been looking into how to best publish a Julia package, and people posted solutions including the minted package for LaTeX. I thought about making a new package to parse each module / function / struct and then output the strings to LaTeX/XeTeX with minted, but the documents produced by Documenter.jl look really great already.

For regular documentation hosting purposes, including the source would get unruly pretty quick. However, for archival purposes or for publishing, it might be helpful to have the option to include each function / struct's source code in the docstring automatically.

Just a thought. Are there any glaring issues / complications with a feature like this? Or does this belong somewhere else (another package, as I mentioned above)?

[MichaelHatherly]

Best option may be to implement a custom abbreviation using https://github.com/JuliaDocs/DocStringExtensions.jl, which should be able to achieve most of what you're looking for.

Edit: as some starter code, this will get you going:

struct SourceCode <: Abbreviation end
const SOURCECODE = SourceCode()

export SOURCECODE

function format(abbrv::SourceCode, buf, doc)
    file = doc.data[:path]
    if isfile(file)
        lines = Base.Iterators.drop(eachline(file), doc.data[:linenumber] - 1)
        text = join(lines, '\n')
        _, from = Meta.parse(text, 1; greedy=false)
        _, to = Meta.parse(text, from)
        println(buf, "```julia")
        println(buf, rstrip(text[from:to]))
        println(buf, "```")
    end
    return nothing
end

Then just use $SOURCECODE in any docstrings you want the source for:

"""
$SOURCECODE
"""
function foo(x)
    # ...
end

[cadojo]

Best option may be to implement a custom abbreviation using https://github.com/JuliaDocs/DocStringExtensions.jl, which should be able to achieve most of what you're looking for.

Edit: as some starter code, this will get you going:

This is great, thanks so much for the quick reply and code. I tried this out in my package, and it displays the code perfectly.

Do you know of any way to have abbreviations only work in some output formats, and not others? For example - set SOURCECODE to display when makedocs(format=:latex, ... and to _not_ display when makedocs(format=Documenter.HTML(), ...)?

I haven't seen this option in DocStringExtensions, because it seems like all docstrings are outputted to Markdown first, and _then_ they are exported to HTML or Latex (or another option). Still, I figured I'd ask in case I was misunderstanding how DocStringExtensions and/or Documenter works.

An alternative option might be to have a separate branch with $SOURCECODE appended to each docstring, and format set to :latex in makedocs. That branch could be automatically rebased over the top of a repository's development branch with a simple GitHub action.

[MichaelHatherly]

with $SOURCECODE appended to each docstring

See @template for how to avoid having to do this manually.

That branch could be automatically rebased over the top of a repository's development branch with a simple GitHub action.

Probably easiest to make format(abbrv::SourceCode, buf, doc) definition above print to buf only if you set a global to true. You'll need to restart your Julia session between each run though since docstrings are cached the first time they are accessed, i.e. you can't change it dynamically during a session.