DocumenterCodeBlocks.jl announcement

Package Announcements
,
1

I want to to announce DocumenterCodeBlocks.jl, a Documenter.jl plugin that makes the code blocks in your package documentation quite a bit more interesting. To enable it the only thing you have to change is to pass the CodeBlocks() to Documenter.makedocs:

using Documenter, DocumenterCodeBlocks

makedocs(
    # ...
    plugins = [CodeBlocks()],
)

I think that the defaults are good, but some things can be configured by passing keyword arguments to the constructor, see the documentation.

The best way to get a feel for it is the documentation itself. Every code block there is rendered by the plugin, so hover, click, and select away. Here is what you get:

Reference links and hover tooltips

Identifiers in code blocks that name a documented object become links to their docstring. Resolution is call-arity aware: foo(1, 2) links to the foo(a, b) method documentation, not just to “some docstring for foo”. Every link also gets a doxygen-style hover tooltip with the target’s signature and a one-line summary:

tooltips

Links only attach where the syntax vouches for the meaning (call callees like add_numbers(...) and type positions like m::MyType) and names that don’t resolve are silently left alone. For ambiguous references, e.g. a splatted call measure(args...) that could hit several methods, the tooltip shows the “arity-pruned” candidate list instead, as seen at the end of the clip above.

Line numbers and linkable lines

Every code block gets GitHub-style line numbers with a content-addressed permalink. Clicking the gutter selects a line, shift-click or drag selects a range, and the selection is reflected in the URL as a stable fragment like #c-1a2b3c4d-L5-L11. Selections survive reload and scroll into view on page load.

linenumbers

The copy code block button is unaffected, the gutter numbers never end up in your clipboard.

Build-time syntax highlighting with JuliaSyntax

Julia code blocks are highlighted at build time using JuliaSyntax.jl instead of highlight.js’s regex approximation. This means correct handling of the tricky cases (nested string interpolation, command literals, type parameters, word operators, etc) and more granularity. Works for julia, julia-repl, jldoctest, and executed @repl blocks (including their ANSI-colored output):

highlight-mocha
highlight-mocha1520×450 34.3 KB

The screenshot is using the catppuccin-mocha theme but all six default Documenter themes are supported.

Docstring-quality warnings

The tooltips are only as good as the docstrings they summarize, so the plugin can optionally warn when a docstring is missing a leading signature block or a short first sentence.

Installation

julia> import Pkg

julia> Pkg.add("DocumenterCodeBlocks")

Status and caveats

The plugin necessarily builds on some Documenter internals beyond the documented plugin API so there might have to be updates to this package for new Documenter releases. If you maintain docs for a package, I’d love for you to try it out and report anything that breaks. Feedcback, issues and PRs are very welcome!

Thanks!

7 Likes