Feature request / question: automatic collection of doc pages entry

[charleskawczynski]

This is more of a request / question. I'd like to know if this added feature is something that could be incorporated into Literate, or if it's better for Documenter, or just create a separate package.

The gist of the feature (pages_array) is that the nested pages array of Pair's is automatically determined from a given directory tree with .jl literate tutorials. For example, assuming a literate_examples folder in the package, the generated markdown files are grabbed from

# After generating markdown files in `generated_dir` directory
tutorials_generated = [joinpath(root, f) for (root, dirs, files) in Base.Filesystem.walkdir(generated_dir) for f in files]
tutorials_md = filter(x -> endswith(x, ".md"), tutorials_generated)
tutorials_md = map(x -> String(last(split(x, joinpath("docs", "src")))), tutorials_md)

tutorials = pages_array(tutorials_md) # Main feature function

pages = Any[
    "Home" => "index.md",
    "Installation" => "Installation.md",
    "Tutorials" => tutorials,
    ...
]

[johnnychen94]

FYI, I've made a package DemoCards that handles a similar task. A live example can be found at https://juliaimages.org/latest/democards/examples/

I do have plans to support this feature there: JuliaDocs/DemoCards.jl#27

[charleskawczynski]

Thanks for the info! I may just make this a separate package since I'd like to keep a light set of dependencies. I'll do that for now and see if it can be incorporated here or in Documenter. Update: I've created the package AutoPages.jl.

[fredrikekre]

This seems like a common enough pattern that I also use myself so might make sense to add the functionality here.

[fredrikekre]

Of course, you can already compose it pretty easily with broadcasting:

pages = readdir("tutorials-src"; join=true)
Literate.markdown.(pages, out)

[charleskawczynski]

Ok, thanks. I've added some tests and useful functionality. Feel free to grab/modify whatever from AutoPages.jl.