Accept .jmd files?

[rafaqz]

Could documenter accept .jmd files from Weave.jl in the pages kwarg? Currently I'm just making a copy with an md extension.

[ChrisRackauckas]

In DiffEq I would like to embed some of the DiffEqBenchmarks and DiffEqTutorials into the documentation, but keep them as separate auto-generating (since some of those benchmarks take more than a day!). Since we already generate the HTML, is there an easy way to make that HTML get the sidebar and just get "in the docs"?

Xref SciML/DiffEqDocs.jl#313
@kanav99

[mortenpi]

Actually, I am not 100% what is being asked here:

@rafaqz Documenter doesn't know how to parse and run Weave blocks. So I am not really sure how we could accept Weave source files.

@ChrisRackauckas Do you mean have Documenter extract the main part of a page from an already compiled HTML page? I don't really see how we could easily do that.

For the benchmark use case, couldn't you just generate a set of .md files every day that you could use as input to Documenter?

[ChrisRackauckas]

Interesting idea. What kind of markdown should I generate?

http://weavejl.mpastell.com/stable/usage/#Supported-output-formats-1

[mortenpi]

Do you just use them as input for Documenter? Then the standard Julia flavored Markdown that we write the documentation in. I wouldn't look at Weave at all. Or do you also want to compile them with Weave?

Edit: Or are you using Weave files to do the benchmarks?

[ChrisRackauckas]

I need to do it with Weave because these are multi-day long benchmarks. They are all already being generated:

https://github.com/JuliaDiffEq/DiffEqBenchmarks.jl
https://benchmarks.juliadiffeq.org/html/MultiLanguage/wrapper_packages.html

I can easily kick out those other formats as well. So would github, hugo, or pandoc markdown be best?

[mortenpi]

So would github, hugo, or pandoc markdown be best?

No idea, to be honest, needs to be tested. Markdown being Markdown, they all have some subtle differences. On the other hand, I would assume that Weave's output is (1) pretty limited in terms of what Markdown features it uses, and (2) pretty regular. So any of them may quite reliably give a good result.

But for more reliability, I would see if Weave could maybe output JFM directly. Then those outputs could easily be used as inputs for Documenter.

[rafaqz]

I'm just trying to reduce duplication by using the weave files as docs pages without actually weaving them. The code blocks just become example code and doctests.

The make.jl run produces web docs, notebooks and pdfs form one source. Currently I just strip the yaml and swap the weave blocks to doctests with some custom code, and copy the file to an md extension.

https://github.com/cesaraustralia/GrowthMaps.jl/blob/master/docs/make.jl

This could be integrated into Documenter.jl and standardised so it's easy to produce the docs, pdf, notebook combo form one source.

[odow]

Is this still an issue?

I don't really see it being a Documenter.jl feature. Instead, packages like Literate and Weave should make it easy to generate Documenter-compatible markdown files. (Literate already does this, https://github.com/fredrikekre/Literate.jl, I haven't used Weave but I assume it's similar.)

JuMP uses Literate to embed all of our tutorials and examples into the documentation. It works great. Here's one example: https://jump.dev/JuMP.jl/v0.21/tutorials/Nonlinear%20programs/space_shuttle_reentry_trajectory/

[odow]

I'm doing a triage of open documenter issues and closing issues that are stale. If I've made a mistake, please re-open

Closing as stale. Documenter doesn't need to do anything here, it's up to other packages to generate Documenter-compatible Markdown.