From what I’ve seem, Documenter.jl is almost the only tool used, because of macros like @docs, index generation, easy github actions and so on. However, coming from R, Quarto seems a much more natural choice to me. With Quarto I can easily render the same document as a pdf, interactive presentation, epub, and so on. I use it daily in my work to generate thousands of interactive reports and API manuals.
I have the impression that Documenter pages look a bit “the same” and can’t be customized: can’t have headers, TOC on the right side, etc. Compare the show cases below:
So: has anyone tried to create the documentation of a Julia package using Quarto, or is it a vain struggle?
I would be quite interested at least when someone tries this!
For now I am using a mix, where my quarto notebooks are rendered to markdown first and that is then taken up by documenter. I have to admit, setting that up was a bit complicated, especially due to the python required for quarto.
Thanks for pointing it out! Can you give a brief explanation of what this PR does? What I understood was this: we will be able to write a Literate script with (almost) all the annotations that Quarto provide, then compile it to a Quarto file. So I will be able to generate automatic doc pages with Documenter macros, but with Quarto. Then I can, if needed, further edit these Quarto documents. Is that correct?
I too spent some time configuring Jupyter and etc to get it working on VSCode (it worked really simpler when using Julia from Rstudio, but the support for documentation and auto complete is null there).
I reas this post some time ago
And was inspired to do the opposite: get a Documenter file (with automated docs and index) and then write the remaining in Quarto and transform in a nice website.
Sounds like the answer by @fredrikekre is pointing to this. I’ll check it right now
This sounds nice! I was thinking about something similar: given a package, create a “skeleton” website with the documentation, and then add examples and so on using Quarto as usual. And all of this rendered in .qmd files.
But we could start with something way less complicated: given a vector of functions (or a path to a .jl file), create a markdown with the docstrings of these functions. I played around with this idea and created Quartomenter.jl. I defined only one macro @qdoc that creates a block of documentation from a function. The results in Quarto are like this:
It is a simple callout block with the output of @doc macro, with some formatting to create headers of level 3 instead of level 1. In Quarto, I just had to type
Over at GitHub - Deltares/Ribasim: Water resources modeling, we write our documentation completely in Quarto. Note that we don’t use Documenter (yet, as it doesn’t integrate with Quarto), so we’re interested in efforts like Quartomenter to integrate it for the documentation of docstrings.
I’ve tried generating .qmd documents from Documenter a la DocumenterMarkdown, but it turned out to be not that straightforward (different ways of linking/ids/syntax etc).
