docs: add verbosity levels to the docs (#1841)

* docs: add verbosity levels to the docs

* docs: cleanup readme and remove old message

Author: avik-pal

README.md

@@ -1,12 +1,22 @@
 # Reactant.jl
 
-[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://enzymead.github.io/Reactant.jl/stable)
-[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://enzymead.github.io/Reactant.jl/dev)
-[![Build Status](https://github.com/EnzymeAD/Reactant.jl/workflows/CI/badge.svg)](https://github.com/EnzymeAD/Reactant.jl/actions)
+<div align="center">
+
+[![Latest Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://enzymead.github.io/Reactant.jl/dev)
+[![Stable Docs](https://img.shields.io/badge/docs-stable-blue.svg)](https://enzymead.github.io/Reactant.jl/stable)
+
+[![CI](https://github.com/EnzymeAD/Reactant.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/EnzymeAD/Reactant.jl/actions/workflows/CI.yml)
 [![Coverage](https://codecov.io/gh/EnzymeAD/Reactant.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/EnzymeAD/Reactant.jl)
+[![Benchmarks](https://github.com/EnzymeAD/Reactant.jl/actions/workflows/benchmark.yml/badge.svg?branch=main)](https://enzymead.github.io/Reactant.jl/benchmarks/)
+
+[![Downloads](https://img.shields.io/badge/dynamic/json?url=http%3A%2F%2Fjuliapkgstats.com%2Fapi%2Fv1%2Fmonthly_downloads%2FReactant&query=total_requests&suffix=%2Fmonth&label=Downloads)](https://juliapkgstats.com/pkg/Reactant)
+[![Downloads](https://img.shields.io/badge/dynamic/json?url=http%3A%2F%2Fjuliapkgstats.com%2Fapi%2Fv1%2Ftotal_downloads%2FReactant&query=total_requests&&label=Total%20Downloads)](https://juliapkgstats.com/pkg/Reactant)
 
-> [!WARNING]  
-> This package is under active development at the moment and may change its API and supported end systems at any time. End-users are advised to wait until a corresponding release with broader availability is made. Package developers are suggested to try out Reactant for integration, but should be advised of the same risks.
+[![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
+[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
+[![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/JuliaDiff/BlueStyle)
+
+</div>
 
 Reactant takes Julia function and compile it into MLIR and run fancy optimizations on top of it, including using EnzymeMLIR for automatic differentiation, and create relevant executables for CPU/GPU/TPU via XLA. It presently operates as a tracing system. Compiled functions will assume the same control flow pattern as was originally taken by objects used at compile time, and control flow (e.g. if, for) as well as any type instabilities will be removed. The benefits of this approach is immediately making all such code available for advanced optimization with little developer effort. This system and corresponding semantics is subject to change to a (potentially partial) source rewriter in the future.
 
@@ -16,7 +26,7 @@ Reactant provides two new array types at its core, a ConcreteRArray and a Traced
 using Reactant
 
 julia_data = ones(2, 10)
-reactant_data = Reactant.ConcreteRArray(julia_data)
+reactant_data = Reactant.to_rarray(julia_data)
 ```
 
 You can also create a ConcreteRArray-version of an arbitrary data type by tracing through the structure, like below. This method will automatically handle recursive data structures or shared objects.
@@ -30,13 +40,13 @@ end
 pair = Pair(ones(3), ones(10))
 
 reactant_pair = Reactant.to_rarray(pair)
-``` 
+```
 
 To compile programs using ConcreteRArray's, one uses the compile function, like as follows:
 
 ```julia
-input1 = Reactant.ConcreteRArray(ones(10))
-input2 = Reactant.ConcreteRArray(ones(10))
+input1 = Reactant.to_rarray(ones(10))
+input2 = Reactant.to_rarray(ones(10))
 
 function sinsum_add(x, y)
    return sum(sin.(x) .+ y)

docs/src/introduction/FAQs.md

@@ -19,6 +19,7 @@ When you encounter OOM (Out of Memory) errors, you can try to clear the cache by
 Julia's builtin `GC.gc()` between memory-intensive operations.
 
 !!! note
+
     This will only free memory which is not currently live. If the result of compiled
     function was stored in a vector, it will still be alive and `GC.gc()` won't free it.
 
@@ -85,7 +86,7 @@ After using Julia's built-in `GC.gc()`:
 ## Benchmark results feel suspiciously fast
 
 If you see benchmark results that are suspiciously fast, it's likely because the benchmark
-was executed with compiled functions where `sync=false` was used (the default). In this case, the compiled 
+was executed with compiled functions where `sync=false` was used (the default). In this case, the compiled
 function will be executed asynchronously, and the benchmark results will be the time it takes
 for the function to schedule the computation on the device. Compile functions with `sync=true` to get the actual runtime. You can also use the `Reactant.synchronize` on the result of the computation to block until the computation is complete.
 
@@ -106,13 +107,13 @@ y = Reactant.to_rarray(rand(Float32, 1000))
 @benchmark f($x, $y) setup=(f = @compile sync=false myfunc($x, $y))
 ```
 
-```
+```julia
 BenchmarkTools.Trial: 199 samples with 9 evaluations per sample.
  Range (min … max):  2.926 μs … 14.333 μs  ┊ GC (min … max): 0.00% … 0.00%
  Time  (median):     3.607 μs              ┊ GC (median):    0.00%
  Time  (mean ± σ):   4.210 μs ±  1.968 μs  ┊ GC (mean ± σ):  0.00% ± 0.00%
 
-   █▅▄▂                                                       
+   █▅▄▂
   ▇█████▇█▅▅▃▃▂▃▄▂▂▁▁▂▁▁▂▁▁▁▁▁▂▁▁▁▁▂▁▁▁▃▁▁▁▁▁▂▁▁▁▁▁▁▁▂▃▁▂▁▁▃ ▂
   2.93 μs        Histogram: frequency by time        12.5 μs <
 
@@ -123,35 +124,45 @@ BenchmarkTools.Trial: 199 samples with 9 evaluations per sample.
 @benchmark f($x, $y) setup=(f = @compile sync=true myfunc($x, $y))
 ```
 
-```
+```julia
 BenchmarkTools.Trial: 221 samples with 8 evaluations per sample.
  Range (min … max):   8.974 μs … 42.443 μs  ┊ GC (min … max): 0.00% … 0.00%
  Time  (median):     11.688 μs              ┊ GC (median):    0.00%
  Time  (mean ± σ):   12.264 μs ±  3.070 μs  ┊ GC (mean ± σ):  0.00% ± 0.00%
 
-    █▃ ▅▇██▃▄ ▄█▃▄▂▅ ▇ ▂    ▂                                  
+    █▃ ▅▇██▃▄ ▄█▃▄▂▅ ▇ ▂    ▂
   ▇▆████████████████▇███▇▃▆▆██▅▅▅▆▆▅▇▁▆▁▁▃▁▃▁▆▁▁▃▁▁▁▁▃▁▁▁▅▁▁▅ ▅
   8.97 μs         Histogram: frequency by time        20.2 μs <
 
  Memory estimate: 400 bytes, allocs estimate: 14.
 ```
 
 ```julia
-@benchmark begin 
-    result = f($x, $y); 
-    Reactant.synchronize(result) 
+@benchmark begin
+    result = f($x, $y);
+    Reactant.synchronize(result)
 end setup=(f = @compile sync=false myfunc(x, y))
 ```
 
-```
+```julia
 BenchmarkTools.Trial: 233 samples with 8 evaluations per sample.
  Range (min … max):   8.911 μs … 19.609 μs  ┊ GC (min … max): 0.00% … 0.00%
  Time  (median):     12.479 μs              ┊ GC (median):    0.00%
  Time  (mean ± σ):   12.758 μs ±  2.219 μs  ┊ GC (mean ± σ):  0.00% ± 0.00%
 
-       ▁▄▄▄▃▂▁   ▃  ▄█▂ ▆▄▂ ▃    ▁  ▃   ▁                      
+       ▁▄▄▄▃▂▁   ▃  ▄█▂ ▆▄▂ ▃    ▁  ▃   ▁
   ▄▃▄▆▆████████▆██▆▇███▆███▇█▄▄▆██▇▇█▇▆▄██▇▁▆▄▃▃▁▁▁▁▃▁▁▁▁▄▁▁▃ ▄
   8.91 μs         Histogram: frequency by time        19.3 μs <
 
  Memory estimate: 400 bytes, allocs estimate: 14.
-```
+```
+
+## XLA verbosity flags
+
+XLA has special logging flags that can be used to get more information about the compilation
+process. These flags are:
+
+1. `TF_CPP_MAX_VLOG_LEVEL`: This set the max verbosity level for XLA, i.e. all logging
+   for `VLOG(level)` where `level <= TF_CPP_MAX_VLOG_LEVEL` will be printed.
+2. `TF_CPP_MIN_VLOG_LEVEL`: This set the min verbosity level for XLA, i.e. all logging
+   for `VLOG(level)` where `level >= TF_CPP_MIN_VLOG_LEVEL` will be printed.