From 24bd19b8934407e05a9ab02c6e3865fdba4868a4 Mon Sep 17 00:00:00 2001
From: Alexius Wadell <awadell@gmail.com>
Date: Tue, 21 Nov 2023 08:27:29 -0500
Subject: [PATCH] wip: docs

---
 docs/Project.toml     |  1 +
 docs/make.jl          | 16 ++++++++++------
 docs/src/.gitignore   |  1 +
 docs/src/jogger.md    | 12 ++++++++++++
 docs/src/profiling.md | 27 +++++++++++++++++++++++++++
 src/jogger.jl         | 13 ++++++++++---
 6 files changed, 61 insertions(+), 9 deletions(-)
 create mode 100644 docs/src/.gitignore
 create mode 100644 docs/src/profiling.md

diff --git a/docs/Project.toml b/docs/Project.toml
index 22b972f..e45133a 100644
--- a/docs/Project.toml
+++ b/docs/Project.toml
@@ -3,6 +3,7 @@ BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Example = "4b09cd0b-9172-4840-a79f-b48550c7f881"
 PkgJogger = "10150987-6cc1-4b76-abee-b1c1cbd91c01"
+Profile = "9abbd945-dff8-562f-b5e8-e1ebf5ef1b79"
 
 [compat]
 Documenter = "1.2"
diff --git a/docs/make.jl b/docs/make.jl
index 127f3e1..8b5ca75 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -20,11 +20,14 @@ DocMeta.setdocmeta!(PkgJogger, :DocTestSetup, :(using PkgJogger); recursive=true
 index_md = joinpath(@__DIR__, "src", "index.md")
 readme_md = joinpath(@__DIR__, "..", "README.md")
 open(index_md, "w") do io
-    write(io, """
-    ```@meta
-    EditURL = "$readme_md"
-    ```
-    """)
+    write(
+        io,
+        """
+```@meta
+EditURL = "$readme_md"
+```
+"""
+    )
     write(io, read(readme_md, String))
 end
 
@@ -37,13 +40,14 @@ makedocs(;
         prettyurls=get(ENV, "CI", "false") == "true",
         canonical="https://awadell1.github.io/PkgJogger.jl",
         assets=String[],
-        analytics = "G-V9E0Q8BDHR",
+        analytics="G-V9E0Q8BDHR",
     ),
     pages=[
         "Home" => "index.md",
         "Jogger" => "jogger.md",
         "Saving Results" => "io.md",
         "Continuous Benchmarking" => "ci.md",
+        "Profiling" => "profiling.md",
         "Reference" => "reference.md",
     ],
     checkdocs=:all,
diff --git a/docs/src/.gitignore b/docs/src/.gitignore
new file mode 100644
index 0000000..fc0ab8a
--- /dev/null
+++ b/docs/src/.gitignore
@@ -0,0 +1 @@
+index.md
diff --git a/docs/src/jogger.md b/docs/src/jogger.md
index 9d16987..81a6d41 100644
--- a/docs/src/jogger.md
+++ b/docs/src/jogger.md
@@ -83,6 +83,17 @@ would have keys of `["bench_subdir", "bench_filename.jl", ...]`, instead of
 > run the suite of a single file, you can `include` the file and run it with:
 > `tune!(suite); run(suite)`
 
+## Filtering Benchmarks
+Often it's useful to run only a subset of the full benchmarking suite.
+For example, to run only the benchmarks within `benchmark/bench_filename.jl`:
+`JogExample.run("bench_filename")`.
+
+Most jogger functions support filtering ([`judge`](@ref JogExample.judge) is a notable exception).
+Greater support is planned.
+
+!!! compat PkgJogger 0.6.0
+    Support for filtering via [`JogExample.suite`](@ref) was added in v0.6.0
+
 ## Jogger Reference
 
 Jogger modules provide helper methods for working with their package's
@@ -93,6 +104,7 @@ Example`.
 JogExample.suite
 JogExample.benchmark
 JogExample.run
+JogExample.profile
 JogExample.save_benchmarks
 JogExample.load_benchmarks
 JogExample.judge
diff --git a/docs/src/profiling.md b/docs/src/profiling.md
new file mode 100644
index 0000000..342726b
--- /dev/null
+++ b/docs/src/profiling.md
@@ -0,0 +1,27 @@
+# Profiling Benchmarks
+
+PkgJogger has support for profiling existing benchmarks using one of the [Supported Profilers](#supported-profilers),
+support for profiling is currently limited. Notably:
+
+1. Only a single benchmark can be profiled at a time
+2. Automated saving or loading of profile results is not supported
+
+## Supported Profilers
+
+
+### CPU
+```@docs
+PkgJogger.profile(::Val{:cpu}, ::Any, ::PkgJogger.BenchmarkTools.Benchmark)
+```
+
+### Allocations
+
+```@docs
+PkgJogger.profile(::Val{:allocs}, ::Any, ::PkgJogger.BenchmarkTools.Benchmark)
+```
+
+### GPU
+
+```@docs
+PkgJogger.profile(::Val{:cuda}, ::Any, ::PkgJogger.BenchmarkTools.Benchmark)
+```
diff --git a/src/jogger.jl b/src/jogger.jl
index 7db1bf8..8b4fcec 100644
--- a/src/jogger.jl
+++ b/src/jogger.jl
@@ -264,10 +264,17 @@ macro jog(pkg)
             At this time, `PkgJogger` only supports profiling a single benchmark
             at a time. Automated saving is not supported.
 
-        # Available Profilers
-        The following profilers are currently supported. Additional profilers
-        are available via package extensions.
+        ## Available Profilers
+        The following profilers have been implemented, but may not be currently
+        loaded (See [Loaded Profilers](#loaded-profilers)).
+
+        - `:cpu` - loaded by default
+        - `:allocs` - loaded if `Profile.Allocs` exists (>=v1.8)
+        - `:cuda` - loaded if the CUDA and NVTX packages are loaded
 
+        ## Loaded Profilers
+        The following profilers are currently loaded. Additional profilers
+        are available via package extensions.
 
         $(@doc PkgJogger.profile)