Add Quarto support - Githubissues

svilupp commented 2 years ago

Closes #199

Changes:

parse properly Quarto arguments #| echo:false
provide Quarto-specific codefence (refactored to a separate function)
save files with extension .qmd
all functionality tested
updated documentation with the new flavor

All tests are passing Code formatted with JuliaFormatter (default setting as no specific preference was indicated)

fredrikekre commented 2 years ago

Thanks for the PR. Can you drop all the formatting changes? Very difficult to review otherwise.

svilupp commented 2 years ago

Thanks for the PR. Can you drop all the formatting changes? Very difficult to review otherwise.

Yes, of course. I've reverted it. I can open a separate PR with JuliaFormatter later.

svilupp commented 2 years ago

Hi @fredrikekre, would you have any thoughts on the PR?

fredrikekre commented 2 years ago

I'm om vacation but will have a look in a week or two.

svilupp commented 1 year ago

Hi @fredrikekre, I was wondering if you have any thoughts on the PR?

My team and I have been using it for several months now, so it seems to work pretty well.

svilupp commented 1 year ago

Hi @fredrikekre, I was wondering if there is anything I can do to get this merged.

I've updated to the latest and re-ran tests. All pass, including the additions for the functionality added.

Are there any suggestions or concerns that you have about this tweak?

lbenet commented 1 year ago

Is there an easy way to test your proposal (using my own .qmd files)?

svilupp commented 1 year ago

Is there an easy way to test your proposal (using my own .qmd files)?

Yeah, very simple. Just add my branch of Literate, eg, in your environment: ]add https://github.com/svilupp/Literate.jl.git#add-quarto-support

and then simply using Literate; Literate.markdown("filename.jl",flavor=Literate.QuartoFlavor())

My workflow is to have it in the global environment and call it with VSCode tasks. Ie, I simply click on "JL to HTML" when I have my script opened and separate process is spun to produce my Quarto report (while I can keep working in my project)

Example tasks.json (in VSCode)

    "version": "2.0.0",
    "tasks": [
        {
            "label": "JL to HTML",
            "type": "shell",
            "command": "echo Finished conversion to HTML",
            "dependsOrder": "sequence",
            "dependsOn": ["JL to QMD", "QMD: HTML Render"]
        },
        {
            "label": "JL to QMD",
            "type": "shell",
            "command": "julia --startup-file=no -e 'using Literate; Literate.markdown(\"${file}\",\"${fileDirname}\",flavor = Literate.QuartoFlavor(),credit=false)'"

        },
                {
            "label": "QMD: HTML Render",
            "type": "shell",
            "command": "quarto render ${fileDirname}${pathSeparator}${fileBasenameNoExtension}.qmd --to html",
            "problemMatcher": []
        }]

FYI. I think I'll create a fork/package extension to be able to register it and add it like a normal package.

svilupp commented 1 year ago

Docs checked. Output formats page renders correctly.

The question is where we should add also a full example to show the application / make it easier to start

fredrikekre commented 1 year ago

Thanks, will have a look.

The question is where we should add also a full example to show the application / make it easier to start

I have been thinking for some time to have a section where I link to real life usage of Literate as inspiration for setups etc. If you have something public let me know and I will get around to write up something.

svilupp commented 1 year ago

I have been thinking for some time to have a section where I link to real life usage of Literate as inspiration for setups etc. If you have something public let me know and I will get around to write up something.

Sorry, I forgot to reply. No, I don't have anything public, but I could easily sanitize a few examples to show the different quarto features (to be hosted in Literate.jl)

svilupp commented 1 year ago

I've looked into the Docs failure. It doesn't seem to be related.

I've refreshed Manifest.toml and local build works without a problem.

Looking at the failure, it's coming from StatsBase and Plots. I suspect it's due to https://github.com/JuliaStats/StatsBase.jl/pull/840 and its removal of type aliases ("ERROR: LoadError: UndefVarError: Float not defined".

I'm unsure how to force Github Actions to load more up-to-date deps (I can build locally with StatsBase 0.34 vs StatsBase 0.33.21 in the CI)

fredrikekre commented 1 year ago

I've refreshed Manifest.toml and local build works without a problem.

You have to commit the changes then too.

I will review and merge this week, I should have some time. Sorry again for slow responses

svilupp commented 1 year ago

You have to commit the changes then too.

Sorry, I didn't make myself clear. I couldn't replicate the error locally, I merely deleted and re-instantiated my Manifest.toml to check if its some breaking release (no changes to Project.toml, so nothing to commit)

To replicate the error, I'd have to explicitly ]add SortingAlgorithms@1.0.1, which breaks. I'm hesitant to add a compat bound, because it's a 2nd-order dependency (docs -> Plots.jl -> StatsBase.jl -> SortingAlgorithms).

We could force Plots to something higher (1.38), but I'm not sure when the issue was introduced, so we could be overly restrictive.

Would you prefer to be safe and set compat to Plots@1.38?

fredrikekre commented 1 year ago

I couldn't replicate the error locally, I merely deleted and re-instantiated my Manifest.toml to check if its some breaking release (no changes to Project.toml, so nothing to commit)

The manifest is commited.

svilupp commented 1 year ago

The manifest is commited.

Oh, I didn't clock that -- that explains the issues. I've committed my Manifest (I run on an arm-based Mac machine, but hopefully nothing in there is platform specific)

svilupp commented 1 year ago

@fredrikekre, are you perhaps at JuliaCon? We could meet up and discuss the next steps?

fredrikekre commented 1 year ago

I wasn't. I think we can merge this. Perhaps in a version 3.0 it make sense to split up the flavors into Literate.quarto etc instead of trying to push it all into Literate.markdown.

svilupp commented 1 year ago

Hi @fredrikekre, would you mind merging this PR?

We're considering giving a presentation on benefits of Literate.jl + Quarto, but it would be odd to ask people to install from a fork... I'm happy to review the structure for 3.0.

Updates:

updated to latest main
tests pass (tested on 1.10 and 1.9)
docs build

If people open issues related to the quarto functionality, just tag me. I have a lot of experience debugging it :)

Thank you!

svilupp commented 1 year ago

Happy Monday, @fredrikekre!

Is there something that I can do to get this merged?

Thank you

svilupp commented 9 months ago

Hi @fredrikekre ,

Hope all is well! Is there any chance we could reach a conclusion on the PR?

I've responded in August to your comments but haven't heard back. The current version isn't perfect but it works well for everyone (we have a bunch of people using it) and is simple to pick up as it follows an easy mental model -- could we consider merging this or rejecting this?

I'm happy to fork into LiterateQuarto.jl, because this is the only useful functionality of Literate for us. However, I'm conscious that forks duplicate work, so I was hoping to prevent it.

Would you prefer we abandon this PR and create a separate package?

Thank you in advance for your response.

fredrikekre commented 9 months ago

I was waiting for https://github.com/fredrikekre/Literate.jl/pull/200#discussion_r1307628784

svilupp commented 9 months ago

I was waiting for #200 (comment)

Thank you, I havent realized that my explanation wasn’t sufficient. I’ll follow your suggestion and update it within the next few days.

fredrikekre / Literate.jl

Add Quarto support #200