Using Quarto to create package documentation

New to Julia
, ,
1

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.

Here are some books and sites made with Quarto:

https://r4ds.hadley.nz/

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?

6 Likes
2

Update: using the @doc macro doesn’t seen so bad. Example: using it in the middle of a document like this

::: {.callout-note}

## Docs

```{julia}

#| echo: false

@doc @assert

```

:::

returns the following image:

image
image741×557 42.7 KB

3

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.

1 Like
4

Both of you are probably interested in https://github.com/fredrikekre/Literate.jl/pull/200 then. Please try it out and review the PR!

6 Likes
5

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?

6

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

7

Here is an interesting project to make Quarto documentation out of python projects APIs: GitHub - machow/quartodoc: Generate API documentation with quarto

I want to test the Literate.jl PR that is aforementioned, but having a seamless way to create documentation from Quarto would be fantastic.

Also, there are some nice documentation with Documenter.jl and mkdocs that looks pretty nice:

https://www.evetion.nl/SpaceLiDAR.jl/dev/

3 Likes
8

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:

image
image1193×980 85.9 KB

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

```{julia}
#| echo: false
@qdoc ball_mapper
```
3 Likes
9

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).

4 Likes
10

Very nice!

What tools do you think would help you, besides the @qdoc macro that I exemplified above?

11

From a Slack thread, someone also shared this:

4 Likes
12

Thanks a lot for the package!

It seems to do create a .qmd for each .jl file with the documentation of each function, which is what I was looking for.

13

After almost a year, I decided to create a tool inspired by R pkgdown using Quarto. You can check at

https://vituri.github.io/QuartoDocBuilder.jl/

6 Likes