Add support for non-Tuple iterators, improve docs and tests

.github/workflows/ci.yml

@@ -16,6 +16,7 @@ jobs:
       matrix:
         version:
           - '1.10'
+          - '~1.11.0-0'
         os:
           - ubuntu-latest
           - macOS-latest

Project.toml

@@ -5,6 +5,13 @@ version = "0.1.2"
 
 [compat]
 julia = "1.10"
+StaticArrays = "1"
+
+[weakdeps]
+StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
+
+[extensions]
+UnrolledUtilitiesStaticArraysExt = "StaticArrays"
 
 [extras]
 Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"

README.md

@@ -1,6 +1,6 @@
 <h1 align="center">
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="logo-white.png">
+  <source media="(prefers-color-scheme: dark)" srcset="logo-dark.png">
   <source media="(prefers-color-scheme: light)" srcset="logo.png">
   <img alt="Shows the logo of UnrolledUtilities.jl" src="logo.png" width="480px">
 </picture>

docs/Project.toml

@@ -5,3 +5,4 @@ JET = "c3a54625-cd67-489e-a8e7-0a5a0ff4e31b"
 OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
 PrettyTables = "08abe8d2-0d0c-5749-adfa-8a2ac140af0d"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+UnrolledUtilities = "0fe1646c-419e-43be-ac14-22321958931b"

docs/make.jl

@@ -2,28 +2,34 @@ using Documenter
 
 include(joinpath("..", "test", "test_and_analyze.jl"))
 
-comparison_table_file = joinpath("docs", "src", "comparison_table.md")
-
-open(comparison_table_file, "w") do io
-    println(io, "# Comparison Table\n```@raw html")
-    println(io, "<div style=\"width: max(80vw, 100%)\">") # use 80% of viewport
-    print_comparison_table(io, true)
-    println(io, "</div>")
-    println(io, "```")
+comparison_tables_file = joinpath("docs", "src", "comparison_tables.md")
+preamble_file = joinpath("docs", "src", "comparison_tables_preamble.md")
+cp(preamble_file, comparison_tables_file; force = true)
+open(comparison_tables_file, "a") do io
+    for (title, comparison_table_dict) in comparison_table_dicts
+        print_comparison_table(title, comparison_table_dict, io)
+    end
 end
 
 makedocs(;
     sitename = "UnrolledUtilities.jl",
     modules = [UnrolledUtilities],
-    pages = ["Home" => "index.md", "Comparison Table" => "comparison_table.md"],
+    pages = [
+        "Home" => "index.md",
+        "Introduction" => "introduction.md",
+        "User Guide" => "user_guide.md",
+        "Developer Guide" => "developer_guide.md",
+        "Comparison Tables" => basename(comparison_tables_file),
+    ],
     format = Documenter.HTML(
         prettyurls = get(ENV, "CI", nothing) == "true",
-        size_threshold_ignore = ["comparison_table.md"],
+        sidebar_sitename = false,
+        size_threshold_ignore = [basename(comparison_tables_file)],
     ),
     clean = true,
 )
 
-rm(comparison_table_file)
+rm(comparison_tables_file)
 
 deploydocs(
     repo = "github.com/CliMA/UnrolledUtilities.jl.git",

docs/src/comparison_tables_preamble.md

@@ -0,0 +1,60 @@
+The following autogenerated tables contain a representative set of potential use
+cases for this package, along with measurements that summarize each case's
+performance, compilation, and memory usage:
+- run time (best of several trial measurements)
+- compilation time (as reported by the compiler)
+- overall level of optimization (type stability, constant propagation, etc.) and
+  allocations during run time (as reported by the garbage collector)
+- total allocations during compilation and first run (as reported by the garbage
+  collector and, when possible, the Julia process's resident set size estimator)
+
+The rows of the tables are highlighted as follows:
+- ```@raw html
+  <span style="color:darkturquoise">light blue </span>
+  ```
+  indicates an improvement in performance due to better optimization and either
+  an improvement or no change in compilation time and total allocations
+- ```@raw html
+  <span style="color:royalblue">dark blue </span>
+  ```
+  indicates an improvement in performance due to better optimization and either
+  slower compilation or more total allocations
+- ```@raw html
+  <span style="color:mediumseagreen">green </span>
+  ```
+  indicates either faster run time or fewer allocations during run time and
+  either an improvement or no change in compilation time and total allocations
+- ```@raw html
+  <span style="color:khaki">yellow </span>
+  ```
+  indicates either faster run time or fewer allocations during run time and
+  either slower compilation or more total allocations
+- ```@raw html
+  <span style="color:mediumorchid">magenta </span>
+  ```
+  indicates no change in performance and either an improvement or no change in
+  compilation time and total allocations
+- ```@raw html
+  <span style="color:silver">light gray </span>
+  ```
+  indicates no change in performance and either faster compilation with more
+  total allocations or slower compilation with fewer total allocations
+- ```@raw html
+  <span style="color:gray">dark gray </span>
+  ```
+  indicates no change in performance and no change in compilation time and total
+  allocations
+- ```@raw html
+  <span style="color:indianred">red </span>
+  ```
+  indicates a deterioration in performance, or no change in performance and
+  either slower compilation or more total allocations
+
+Rows highlighted in gray present no clear advantage to unrolling, while those
+highlighted in red present a clear disadvantage. It is recommended that you only
+unroll when your use case is similar to a row in one of the remaining
+categories, each of which demonstrates some advantage to unrolling.
+
+The tables are also printed out by this package's test suite, so they can be
+compared across different operating systems by consulting the
+[CI pipeline](https://github.com/CliMA/UnrolledUtilities.jl/actions/workflows/ci.yml).