wip: docs

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"

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,

docs/src/.gitignore

@@ -0,0 +1 @@
+index.md

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

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)
+```

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)