DocumenterQuarto

Use Documenter syntax with Quarto.

Overview

What is DocumenterQuarto?

Quarto is a single-source multi-target technical publishing system which can render HTML, PDF, DOCX, and many (many, many) other targets. The source format for Quarto is a flavor of Markdown that allows for executing code, including Julia code! This allows for documentation generation alongside executable code examples.

DocumenterQuarto generates templates for Quarto websites (books, more precisely) which automatically document your Julia package, as well as utility functions to automatically parse Julia's @doc output into Quarto Markdown. The workflow for rendering and publishing your documentation is identical to that of Documenter, so your CI should not need to change too much!

Installation

Choose one of the two lines below!

Pkg.add("DocumenterQuarto")  # in Julia code

pkg> add DocumenterQuarto    # in Julia's REPL

You will also need to download Quarto, and install Jupyter. The simplest option for installing Jupyter is often: python -m pip install --user jupyter.

Usage

Using DocumenterQuarto for your package.

Documenting a New Package

If you don't already have documentation for your package, use the following steps to generate a new documentation website.

1. Navigate to the root directory of your Julia package.
2. Execute the code below.

julia -e 'import Pkg; Pkg.add(url="https://github.com/cadojo/DocumenterQuarto.jl")'
julia -e 'import DocumenterQuarto; DocumenterQuarto.generate()'

Documenting an Existing Package

If your package already has documentation, it is likely that the migration to a Quarto-based website will be easy! At this time, the simplest approach is likely to move your existing documentation, generate a new documentation site with the instructions above, and then move select Markdown files from your old documentation back into your new docs/src directory. There are some tips that are helpful to keep in mind.

1. In Documenter, you use @example to execute (and show) a block of code. In Quarto, this is provided by execution options and code blocks. In most cases, you can simply replace @example with {julia} and the code should execute when your documentation is rendered!
2. All codes are executed in Main, and are scoped to each individual file.
3. To have executable code in your Markdown, you have to use the .qmd file extension.

Quarto and Julia Environments

Quarto may automatically find a Julia environment. If you run into environment issues while rendering, try the following code.

import Pkg
Pkg.activate("docs")
Pkg.develop(path=".")
Pkg.instantiate()

Compatibility with LiveServer

This workflow is fully compatible with LiveServer! If using the make.jl script generated with DocumenterQuarto.generate, then you can serve the documentation locally with the following code.

using LiveServer

servedocs(skip_dir="docs/src/.quarto")

Alternatives

Other excellent documentation packages.

There are plenty of documentation tools and packages in the Julia ecosystem; most of them are more robust and have more developer support than this package! Only a couple of alternative packages are shown below.

• Documenter.jl is the primary documentation package in the Julia ecosystem.

• QuartoDocBuilder.jl is the first Quarto documentation package for Julia, and provides a simpler out-of-the-box Quarto project which looks excellent.