Pass kwargs to literate

miguelbiron commented 2 years ago

Hi -- thank you for this package, it's been most useful in my work.

This PR implements the ability to pass optional kwargs to Literate.Markdown(). The use case that motivated me to add this feature is avoiding the additional run in Documenter of expensive simulations. This can be achieved by generating all required assets in the makedemos call, and then telling Literate to put code inside ````julia```` blocks instead of @example blocks via the codefence argument

examples, examples_cb, examples_assets = makedemos(
    "examples", 
     literate_kwargs = (
         codefence   = ("````julia" => "````")
    )
)

Comments and edits are welcome.

johnnychen94 commented 2 years ago

This is a great improvement to the build pipeline -- I was also wondering what can be done to reduce the build time but didn't realize codefence is the solution.

I believe you have noticed how jupyter notebooks can be disabled in DemoCards. -- DemoCards tries to keep the configuration into config.json file, so perhaps we can make it to something like:

{
    "properties":{
        "notebook": "false",
        "execution": "false",
    }
}

where "execution" passes the codefence = "```julia```=>"```" to Literate. (I'm not sure if "execution" is a good name, so feel free to use whatever sounds good to you -- may be execute_documenter?)

The good part of this is that one can choose to put this config wherever he wants: 1) page configuration, 2) section configuration, or 3) file configuration.

Also, leaving a few docs and tests could be very much helpful!

FWIW, #98 is how I added opt-out support for the notebook.

t-bltg commented 1 year ago

This looks reasonable. Should it go in ?

frankier commented 10 months ago

Hi @miguelbiron . I'm wondering whether this PR https://github.com/JuliaDocs/DemoCards.jl/pull/131 addresses the original use case? Of course some kind of lower level passthrough/escape hatch would be good too (so I'm also +1 this PR).

tshort commented 9 months ago

I'd like this to be able to use Literate's postprocess pass.

frankier commented 9 months ago

If you rebase this PR and add some kind of basic smoke test and some kind of docs I will review + probably merge

JuliaDocs / DemoCards.jl

Pass kwargs to literate #114