https://github.com/cadojo/documenterquarto.jl
Build documentation for your Julia package with Quarto!
https://github.com/cadojo/documenterquarto.jl
Last synced: 3 months ago
JSON representation
Build documentation for your Julia package with Quarto!
- Host: GitHub
- URL: https://github.com/cadojo/documenterquarto.jl
- Owner: cadojo
- License: mit
- Created: 2024-04-14T03:14:43.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-01-09T03:18:25.000Z (4 months ago)
- Last Synced: 2025-01-20T17:54:41.647Z (4 months ago)
- Language: Julia
- Homepage: http://docs.loopy.codes/DocumenterQuarto.jl/
- Size: 558 KB
- Stars: 8
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 📚🌐 Julia Package Documentation via Quarto
*Use [`Documenter`](https://GitHub.com/JuliaDocs/Documenter.jl) syntax with [Quarto](https://quarto.org).*
## Overview
*What is `DocumenterQuarto`?*
[Quarto](https://quarto.org) 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](https://quarto.org/docs/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!*
``` julia
Pkg.add("DocumenterQuarto") # in Julia code
```
``` julia
pkg> add DocumenterQuarto # in Julia's REPL
```
You will also need to download [Quarto](https://quarto.org/docs/get-started/), 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
import Pkg
Pkg.add(url="https://github.com/cadojo/DocumenterQuarto.jl")
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](https://quarto.org/docs/computations/julia.html) 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.
``` julia
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.
``` julia
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`](https://GitHub.com/JuliaDocs/Documenter.jl) is the primary documentation package in the Julia ecosystem.
- [`QuartoDocBuilder.jl`](https://github.com/vituri/QuartoDocBuilder.jl) is the first Quarto documentation package for Julia, and provides a simpler *out-of-the-box* Quarto project which looks excellent.