Completes minimum-viable demonstration

  * Updates workflows
  * Adds new `doc` and `autodoc` functions
  * Adds new `generate` function to create documentation websites
  * Adds documentation via README and website

.devcontainer/devcontainer.json

@@ -0,0 +1,22 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/JuliaLang/devcontainer-templates/tree/main/src/julia
+{
+	"name": "Julia",
+	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+	"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	"features": {
+		// A Feature to install Julia via juliaup. More info: https://github.com/JuliaLang/devcontainer-features/tree/main/src/julia.
+		"ghcr.io/julialang/devcontainer-features/julia:1": {},
+		"ghcr.io/devcontainers/features/python:1": {
+			"installJupyterlab": true
+		},
+		"ghcr.io/devcontainers/features/git-lfs:1": {},
+		"ghcr.io/devcontainers-contrib/features/starship:1": {},
+        "ghcr.io/rocker-org/devcontainer-features/quarto-cli:1": {} 
+
+	},
+	"postCreateCommand": {
+		"Initialize Starship Prompt": "echo eval '$(starship init bash)' >> ~/.bashrc"
+	}
+}

.github/workflows/UnitTests.yml → .github/workflows/CI.yml

@@ -1,13 +1,11 @@
-name: UnitTests
+name: CI
 on:
   push:
     branches:
       - main
 jobs:
   test:
-    name:
-      Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{
-      github.event_name }}
+    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: true
@@ -29,8 +27,7 @@ jobs:
           cache-name: cache-artifacts
         with:
           path: ~/.julia/artifacts
-          key:
-            ${{ runner.os }}-test-${{ env.cache-name }}-${{
+          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{
             hashFiles('**/Project.toml') }}
           restore-keys: |
             ${{ runner.os }}-test-${{ env.cache-name }}-

.github/workflows/CompatHelper.yml

@@ -1,28 +1,44 @@
 name: CompatHelper
-
 on:
   schedule:
-    - cron: '0 5 * * *'
-    - cron: '0 16 * * *'
-  issues:
-    types: [opened, reopened]
+    - cron: 0 0 * * *
   workflow_dispatch:
-
+permissions:
+  contents: write
+  pull-requests: write
 jobs:
-  build:
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        julia-version: [1]
-        julia-arch: [x86]
-        os: [ubuntu-latest]
+  CompatHelper:
+    runs-on: ubuntu-latest
     steps:
-      - uses: julia-actions/setup-julia@latest
+      - name: Check if Julia is already available in the PATH
+        id: julia_in_path
+        run: which julia
+        continue-on-error: true
+      - name: Install Julia, but only if it is not already available in the PATH
+        uses: julia-actions/setup-julia@v2
         with:
-          version: ${{ matrix.julia-version }}
-      - name: Pkg.add("CompatHelper")
-        run: julia -e 'using Pkg; Pkg.add("CompatHelper")'
-      - name: CompatHelper.main()
+          version: "1"
+          arch: ${{ runner.arch }}
+        if: steps.julia_in_path.outcome != 'success'
+      - name: "Add the General registry via Git"
+        run: |
+          import Pkg
+          ENV["JULIA_PKG_SERVER"] = ""
+          Pkg.Registry.add("General")
+        shell: julia --color=yes {0}
+      - name: "Install CompatHelper"
+        run: |
+          import Pkg
+          name = "CompatHelper"
+          uuid = "aa819f21-2bde-4658-8897-bab36330d9b7"
+          version = "3"
+          Pkg.add(; name, uuid, version)
+        shell: julia --color=yes {0}
+      - name: "Run CompatHelper"
+        run: |
+          import CompatHelper
+          CompatHelper.main()
+        shell: julia --color=yes {0}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: julia -e 'using CompatHelper; CompatHelper.main()'
+          COMPATHELPER_PRIV: ${{ secrets.DOCUMENTER_KEY }}

.github/workflows/Documentation.yml

@@ -3,21 +3,30 @@ name: Documentation
 on:
   push:
     branches:
-      - main
-    tags: '*'
+      - main # update to match your development branch (master, main, dev, trunk, ...)
+    tags: "*"
+  pull_request:
 
 jobs:
   build:
+    permissions:
+      actions: write
+      contents: write
+      pull-requests: read
+      statuses: write
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: julia-actions/setup-julia@latest
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
         with:
-          version: '1'
+          version: "1"
+      - uses: quarto-dev/quarto-actions/setup@v2
+      - name: Install Jupyter
+        run: python -m pip install jupyter
+      - uses: julia-actions/cache@v2
       - name: Install dependencies
         run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
       - name: Build and deploy
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
-          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key
         run: julia --project=docs/ docs/make.jl

.github/workflows/Register.yml

@@ -0,0 +1,16 @@
+name: Register
+
+on:
+  workflow_dispatch:
+
+jobs:
+  release:
+    name: Register Package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: peter-evans/commit-comment@v3
+        with:
+          body: |
+            @JuliaRegistrator register"
+
+            This comment was generated with `commit-comment` and [`Register.yml`](/.github/workflows/Register.yml).

.github/workflows/TagBot.yml

@@ -6,7 +6,7 @@ on:
   workflow_dispatch:
     inputs:
       lookback:
-        default: 3
+        default: "3"
 permissions:
   actions: read
   checks: read
@@ -22,8 +22,7 @@ permissions:
   statuses: read
 jobs:
   TagBot:
-    if:
-      github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'
+    if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'
     runs-on: ubuntu-latest
     steps:
       - uses: JuliaRegistries/TagBot@v1

.gitignore

@@ -28,3 +28,6 @@ Manifest.toml
 
 # As should .vscode!
 .vscode
+
+# Python virtual environments
+venv

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Joseph D Carpinelli
+Copyright (c) 2023 Joseph D. Carpinelli
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Project.toml

@@ -1,14 +1,24 @@
-name = "QuartoDocumenter"
+name = "DocumenterQuarto"
 uuid = "73f83fcb-c367-40db-89b6-8fd94701aaf2"
 authors = ["Joey Carpinelli <[email protected]>"]
 version = "0.1.0"
 
 [deps]
+Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Git = "d7ba0133-e1db-5d97-8f8c-041e4b3a1eb2"
+IOCapture = "b5f81e59-6552-4d32-b1f0-c071b021bf89"
 InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
 Quarto = "d7167be5-f61b-4dc9-b75c-ab62374668c5"
+TOML = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
+
+[compat]
+Dates = "1.11.0"
+Git = "1.3.1"
+IOCapture = "0.2.5"
+TOML = "1.0.3"
 
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

README.md

@@ -1,16 +1,89 @@
-[![Tests](https://github.com/cadojo/DocumenterQuarto.jl/workflows/UnitTests/badge.svg)](https://github.com/cadojo/DocumenterQuarto.jl/actions?query=workflow%3AUnitTests)
-[![Docs](https://github.com/cadojo/DocumenterQuarto.jl/workflows/Documentation/badge.svg)](https://cadojo.github.io/DocumenterQuarto.jl)
+# `DocumenterQuarto`
 
-# QuartoDocumenter.jl
+*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!
+*Choose one of the two lines below!*
 
-```julia
-Pkg.add("QuartoDocumenter")  # in Julia code
+``` julia
+Pkg.add("DocumenterQuarto")  # in Julia code
 ```
 
-```julia
-pkg> add QuartoDocumenter    # in Julia's REPL
+``` 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.
+
+``` sh
+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](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.

docs/Project.toml

@@ -0,0 +1,5 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Quarto = "d7167be5-f61b-4dc9-b75c-ab62374668c5"
+DocumenterQuarto = "73f83fcb-c367-40db-89b6-8fd94701aaf2"
+IJulia = "7073ff75-c697-5162-941a-fcdaad2a7d2a"

docs/make.jl

@@ -0,0 +1,6 @@
+using Documenter
+using Quarto
+
+Quarto.render(joinpath(@__DIR__, "src"))
+
+Documenter.deploydocs(repo = "https://github.com/cadojo/DocumenterQuarto.jl.git")