Updates documentation

README.md

@@ -1,16 +1,78 @@
-[![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`
 
-# DocumenterQuarto.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
+``` julia
 Pkg.add("DocumenterQuarto")  # in Julia code
 ```
 
-```julia
+``` 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")
+```

docs/src/.gitignore

@@ -0,0 +1 @@
+/.quarto/

docs/src/_quarto.yml

@@ -7,10 +7,12 @@ book:
     author: 
         name: "Joey Carpinelli"
         email: "[email protected]"
-    date: "2024-12-29"
+    date: "2024-12-31"
     chapters:
         - index.md
         - api/index.qmd 
+    sidebar: 
+        search: true
 
 toc-title: "Table of Contents"
 

docs/src/api/index.qmd

@@ -1,4 +1,10 @@
-# API Reference
+---
+number-depth: 2
+---
+
+# Reference
+
+_Docstrings for DocumenterQuarto._
 
 ```{julia}
 #| echo: false
@@ -9,6 +15,12 @@ using DocumenterQuarto
 
 ```{julia}
 #| echo: false
-#| output: true
+#| output: asis
 DocumenterQuarto.autodoc(DocumenterQuarto)
 ```
+
+```{julia}
+#| echo: false
+#| output: asis
+DocumenterQuarto.doc(DocumenterQuarto.generate)
+```

docs/src/index.md

@@ -1,3 +1,5 @@
-# Overview
+---
+title: Overview
+---
 
-_To do: add a description of the project!_
+{{< include ../../README.md >}}

src/DocumenterQuarto.jl

@@ -124,15 +124,32 @@ function generate(; title=nothing, type="book", api="api")
 
     index = joinpath(src, "index.md")
 
-    isfile(index) || open(index, "w") do io
-        write(
-            io,
-            """
-            # Overview
+    isfile(index) || begin
+        if isfile("README.md")
+            open(index, "w") do io
+                write(
+                    io,
+                    """
+                    ---
+                    title: Overview
+                    ---
 
-            _To do: add a description of the project!_
-            """
-        )
+                    {{< include ../../README.md >}}
+                    """
+                )
+            end
+        else
+            open(index, "w") do io
+                write(
+                    io,
+                    """
+                    # Overview
+
+                    _To do: add a description of the project!_
+                    """
+                )
+            end
+        end
     end
 
     project = joinpath(docs, "Project.toml")
@@ -158,7 +175,13 @@ function generate(; title=nothing, type="book", api="api")
             write(
                 io,
                 """
-                # API Reference
+                ---
+                number-depth: 2
+                ---
+
+                # Reference
+
+                _Docstrings for $name._
 
                 ```{julia}
                 #| echo: false
@@ -169,7 +192,7 @@ function generate(; title=nothing, type="book", api="api")
 
                 ```{julia}
                 #| echo: false
-                #| output: true
+                #| output: asis
                 DocumenterQuarto.autodoc($name)
                 ```
                 """
@@ -231,7 +254,7 @@ function process_headers(markdown)
     for (index, item) in enumerate(markdown.content)
         if item isa Markdown.Header
             newlevel = min(level(item) + 2, 6)
-            markdown.content[index] = Markdown.Header{newlevel}(item.text)
+            markdown.content[index] = Markdown.Header{newlevel}(item.text * " {.unnumbered}")
         elseif :content in propertynames(item)
             markdown.content[index] = process_headers(item)
         end