# Using Quarto to create package documentation

**URL:** <https://discourse.julialang.org/t/using-quarto-to-create-package-documentation/102698>\
**Category:** New to Julia\
**Tags:** documentation, documenter, quarto\
**Created:** [August 10, 2023, 10:53pm UTC](https://discourse.julialang.org/t/using-quarto-to-create-package-documentation/102698 "2023-08-10T22:53:43Z")\
**Posts on this page:** 13\
**Page:** 1

<div class="post-metadata">

**Author:** ![vituri](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/vituri/32/50422_2.png) [@vituri](https://discourse.julialang.org/u/vituri)\
**Post date:** [August 10, 2023, 10:53pm UTC](https://discourse.julialang.org/t/using-quarto-to-create-package-documentation/102698/1 "2023-08-10T22:53:43Z")

</div>

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:

> **[Quarto - Using Julia](https://quarto.org/docs/computations/julia.html)**

[https://r4ds.hadley.nz/](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:

> **[Examples · Documenter.jl](https://documenter.juliadocs.org/stable/man/examples/)**
>
> Documentation for Documenter.jl.

So: has anyone tried to create the documentation of a Julia package using Quarto, or is it a vain struggle?

---

<div class="post-metadata">

**Author:** ![vituri](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/vituri/32/50422_2.png) [@vituri](https://discourse.julialang.org/u/vituri)\
**Post date:** [August 11, 2023, 5:11am UTC](https://discourse.julialang.org/t/using-quarto-to-create-package-documentation/102698/2 "2023-08-11T05:11:48Z")

</div>

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

````julia
::: {.callout-note}

## Docs

```{julia}

#| echo: false

@doc @assert

```

:::

````

returns the following image:

 ![image](https://global.discourse-cdn.com/julialang/original/3X/1/0/102064942a1a14e1bfee468aaf5d3dbeb62f98cb.png)

---

<div class="post-metadata">

**Author:** ![kellertuer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kellertuer/32/220707_2.png) [@kellertuer](https://discourse.julialang.org/u/kellertuer)\
**Post date:** [August 11, 2023, 6:38am UTC](https://discourse.julialang.org/t/using-quarto-to-create-package-documentation/102698/3 "2023-08-11T06:38:31Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [August 11, 2023, 6:57am UTC](https://discourse.julialang.org/t/using-quarto-to-create-package-documentation/102698/4 "2023-08-11T06:57:32Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![vituri](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/vituri/32/50422_2.png) [@vituri](https://discourse.julialang.org/u/vituri)\
**Post date:** [August 11, 2023, 12:48pm UTC](https://discourse.julialang.org/t/using-quarto-to-create-package-documentation/102698/5 "2023-08-11T12:48:04Z")

</div>

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?

---

<div class="post-metadata">

**Author:** ![vituri](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/vituri/32/50422_2.png) [@vituri](https://discourse.julialang.org/u/vituri)\
**Post date:** [August 11, 2023, 12:51pm UTC](https://discourse.julialang.org/t/using-quarto-to-create-package-documentation/102698/6 "2023-08-11T12:51:53Z")

</div>

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

> **[Patrick Altmeyer - A year of using Quarto with Julia](https://www.paltmeyer.com/blog/posts/tips-and-tricks-for-using-quarto-with-julia/)**
>
> A short companion post to my presentation on using Quarto with Julia at the 2nd JuliaLang Eindhoven meetup in November, 2022.

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

---

<div class="post-metadata">

**Author:** ![camilogarciabotero](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/camilogarciabotero/32/35000_2.png) [@camilogarciabotero](https://discourse.julialang.org/u/camilogarciabotero)\
**Post date:** [August 13, 2023, 4:09pm UTC](https://discourse.julialang.org/t/using-quarto-to-create-package-documentation/102698/7 "2023-08-13T16:09:47Z")

</div>

Here is an interesting project to make Quarto documentation out of python projects APIs: [GitHub - machow/quartodoc: Generate API documentation with quarto](https://github.com/machow/quartodoc/)

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/](https://www.evetion.nl/SpaceLiDAR.jl/dev/)

---

<div class="post-metadata">

**Author:** ![vituri](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/vituri/32/50422_2.png) [@vituri](https://discourse.julialang.org/u/vituri)\
**Post date:** [August 14, 2023, 2:30am UTC](https://discourse.julialang.org/t/using-quarto-to-create-package-documentation/102698/8 "2023-08-14T02:30:30Z")

</div>

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](https://github.com/vituri/Quartomenter.jl/blob/main/src/docstrings.jl). I defined only one macro `@qdoc` that creates a block of documentation from a function. The results in Quarto are [like this](https://juliatda.github.io/TDAmapper.jl/generalization.html):

 ![image](https://global.discourse-cdn.com/julialang/original/3X/2/6/26b9cbf23d1ad49c174e260cb5f54caa7d5d4faa.png)

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
```{julia}
#| echo: false
@qdoc ball_mapper
```

````

---

<div class="post-metadata">

**Author:** ![evetion](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/evetion/32/22679_2.png) [@evetion](https://discourse.julialang.org/u/evetion)\
**Post date:** [August 14, 2023, 3:02pm UTC](https://discourse.julialang.org/t/using-quarto-to-create-package-documentation/102698/9 "2023-08-14T15:02:02Z")

</div>

Over at [GitHub - Deltares/Ribasim: Water resources modeling](https://github.com/Deltares/Ribasim.jl), we write our [documentation](https://deltares.github.io/Ribasim/) 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).

---

<div class="post-metadata">

**Author:** ![vituri](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/vituri/32/50422_2.png) [@vituri](https://discourse.julialang.org/u/vituri)\
**Post date:** [August 14, 2023, 3:48pm UTC](https://discourse.julialang.org/t/using-quarto-to-create-package-documentation/102698/10 "2023-08-14T15:48:28Z")

</div>

Very nice!

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

---

<div class="post-metadata">

**Author:** ![camilogarciabotero](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/camilogarciabotero/32/35000_2.png) [@camilogarciabotero](https://discourse.julialang.org/u/camilogarciabotero)\
**Post date:** [August 15, 2023, 1:20am UTC](https://discourse.julialang.org/t/using-quarto-to-create-package-documentation/102698/11 "2023-08-15T01:20:25Z")

</div>

From a Slack thread, someone also shared this:

> **[GitHub - medyan-dev/QMDDocTools.jl: A Julia package to auto generate Quarto...](https://github.com/medyan-dev/QMDDocTools.jl)**
>
> A Julia package to auto generate Quarto qmd files from the docstrings in a Julia package - GitHub - medyan-dev/QMDDocTools.jl: A Julia package to auto generate Quarto qmd files from the docstrings ...

---

<div class="post-metadata">

**Author:** ![vituri](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/vituri/32/50422_2.png) [@vituri](https://discourse.julialang.org/u/vituri)\
**Post date:** [August 22, 2023, 4:49am UTC](https://discourse.julialang.org/t/using-quarto-to-create-package-documentation/102698/12 "2023-08-22T04:49:57Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![vituri](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/vituri/32/50422_2.png) [@vituri](https://discourse.julialang.org/u/vituri)\
**Post date:** [May 29, 2024, 8:41pm UTC](https://discourse.julialang.org/t/using-quarto-to-create-package-documentation/102698/13 "2024-05-29T20:41:55Z")

</div>

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/](https://vituri.github.io/QuartoDocBuilder.jl/)