How does code integration in docs work?


#1

Was just browsing the TimeSeries.jl docs (which are broken), in which code is integrated and somehow generated by actually running the code and putting both code and outputs inline.

They seem to be using some sort of macro(!?) like (example taken from here):

@setup int-indexing
using MarketData

@repl int-indexing
ohlc[1]
ohlc[1:3]
ohlc[1:2:10]
ohlc[[1:3;8]]
ohlc[end]
`

How does this work? I’m assuming this is what I’ve seen people refer to as “building docs”, but how does this practically work? Is there a package that does this?


#2

Documenter.jl is used by most packages, and Julia itself.

See https://juliadocs.github.io/Documenter.jl/stable/

See https://juliadocs.github.io/Documenter.jl/stable/man/syntax/


#3

That looks treat, thanks!

Any idea why this would go wrong the way it does in the TimeSeries docs? In the published docs here all examples fail with undefined errors, which seem due to a required package not being loaded, even though the raw docs file on GitHub here looks like it’s doing the right thing in linking @setup and @repl blocks together.


#4

It seems to have been fixed for the docs on the master branch, e.g. http://juliastats.github.io/TimeSeries.jl/dev/indexing/


#5

Ah nice so the raw code on GitHub relates to this and is working after all - just wanted to make sure I’m not looking at an incorrect example of Documenter usage!