Merge pull request #66 from ArnoStrouwen/doc_improv

Doc improv

Author: ChrisRackauckas

.JuliaFormatter.toml

@@ -1 +1,2 @@
-style = "sciml"
+style = "sciml"
+format_markdown = true

.gitignore

@@ -1 +1,2 @@
-/Manifest.toml
+Manifest.toml
+docs/build

README.md

@@ -1,16 +1,14 @@
 # RuntimeGeneratedFunctions.jl
 
-
 [![Join the chat at https://julialang.zulipchat.com #sciml-bridged](https://img.shields.io/static/v1?label=Zulip&message=chat&color=9558b2&labelColor=389826)](https://julialang.zulipchat.com/#narrow/stream/279055-sciml-bridged)
 [![Global Docs](https://img.shields.io/badge/docs-SciML-blue.svg)](https://docs.sciml.ai/RuntimeGeneratedFunctions/stable/)
 
 [![codecov](https://codecov.io/gh/SciML/RuntimeGeneratedFunctions.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/SciML/RuntimeGeneratedFunctions.jl)
 [![Build Status](https://github.com/SciML/RuntimeGeneratedFunctions.jl/workflows/CI/badge.svg)](https://github.com/SciML/RuntimeGeneratedFunctions.jl/actions?query=workflow%3ACI)
 
-[![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)
+[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor%27s%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
 [![SciML Code Style](https://img.shields.io/static/v1?label=code%20style&message=SciML&color=9558b2&labelColor=389826)](https://github.com/SciML/SciMLStyle)
 
-
 `RuntimeGeneratedFunctions` are functions generated at runtime without world-age
 issues and with the full performance of a standard Julia anonymous function. This
 builds functions in a way that avoids `eval`.
@@ -37,7 +35,7 @@ using RuntimeGeneratedFunctions
 RuntimeGeneratedFunctions.init(@__MODULE__)
 
 function no_worldage()
-    ex = :(function f(_du,_u,_p,_t)
+    ex = :(function f(_du, _u, _p, _t)
         @inbounds _du[1] = _u[1]
         @inbounds _du[2] = _u[2]
         nothing
@@ -47,7 +45,7 @@ function no_worldage()
     u = rand(2)
     p = nothing
     t = nothing
-    f1(du,u,p,t)
+    f1(du, u, p, t)
 end
 no_worldage()
 ```
@@ -62,9 +60,9 @@ to the `@RuntimeGeneratedFunction` constructor. For example
 RuntimeGeneratedFunctions.init(@__MODULE__)
 
 module A
-    using RuntimeGeneratedFunctions
-    RuntimeGeneratedFunctions.init(A)
-    helper_function(x) = x + 1
+using RuntimeGeneratedFunctions
+RuntimeGeneratedFunctions.init(A)
+helper_function(x) = x + 1
 end
 
 function g()
@@ -93,13 +91,13 @@ RuntimeGeneratedFunctions.init(@__MODULE__)
 # Imagine HelperModule is in a separate package and will be precompiled
 # separately.
 module HelperModule
-    using RuntimeGeneratedFunctions
-    RuntimeGeneratedFunctions.init(HelperModule)
+using RuntimeGeneratedFunctions
+RuntimeGeneratedFunctions.init(HelperModule)
 
-    function construct_rgf(cache_module, context_module, ex)
-        ex = :((x)->$ex^2 + x)
-        RuntimeGeneratedFunction(cache_module, context_module, ex)
-    end
+function construct_rgf(cache_module, context_module, ex)
+    ex = :((x) -> $ex^2 + x)
+    RuntimeGeneratedFunction(cache_module, context_module, ex)
+end
 end
 
 function g()
@@ -112,4 +110,3 @@ end
 f = g()
 @show f(1)
 ```
-

docs/make.jl

@@ -5,23 +5,25 @@ cp("./docs/Manifest.toml", "./docs/src/assets/Manifest.toml", force = true)
 cp("./docs/Project.toml", "./docs/src/assets/Project.toml", force = true)
 
 makedocs(sitename = "RuntimeGeneratedFunctions.jl",
-         authors = "Chris Rackauckas",
-         modules = [RuntimeGeneratedFunctions],
-         clean = true, doctest = false,
-         strict = [
-             :doctest,
-             :linkcheck,
-             :parse_error,
-             :example_block,
-             # Other available options are
-             # :autodocs_block, :cross_references, :docs_block, :eval_block, :example_block, :footnote, :meta_block, :missing_docs, :setup_block
-         ],
-         format = Documenter.HTML(analytics = "UA-90474609-3",
-                                  assets = ["assets/favicon.ico"],
-                                  canonical = "https://docs.sciml.ai/RuntimeGeneratedFunctions/stable/"),
-         pages = [
-             "RuntimeGeneratedFunctions.jl: Efficient Staged Compilation" => "index.md",
-         ])
+    authors = "Chris Rackauckas",
+    modules = [RuntimeGeneratedFunctions],
+    clean = true, doctest = false, linkcheck = true,
+    strict = [
+        :doctest,
+        :linkcheck,
+        :parse_error,
+        :example_block,
+        :cross_references,
+        # Other available options are
+        # :autodocs_block, :cross_references, :docs_block, :eval_block, :example_block, :footnote, :meta_block, :missing_docs, :setup_block
+    ],
+    format = Documenter.HTML(analytics = "UA-90474609-3",
+        assets = ["assets/favicon.ico"],
+        canonical = "https://docs.sciml.ai/RuntimeGeneratedFunctions/stable/"),
+    pages = [
+        "RuntimeGeneratedFunctions.jl: Efficient Staged Compilation" => "index.md",
+        "API" => "api.md",
+    ])
 
 deploydocs(;
-           repo = "github.com/SciML/RuntimeGeneratedFunctions.jl")
+    repo = "github.com/SciML/RuntimeGeneratedFunctions.jl")

docs/src/api.md

@@ -0,0 +1,5 @@
+# API
+
+```@autodocs
+Modules = [RuntimeGeneratedFunctions]
+```

docs/src/index.md

@@ -26,7 +26,7 @@ using RuntimeGeneratedFunctions
 RuntimeGeneratedFunctions.init(@__MODULE__)
 
 function no_worldage()
-    ex = :(function f(_du,_u,_p,_t)
+    ex = :(function f(_du, _u, _p, _t)
         @inbounds _du[1] = _u[1]
         @inbounds _du[2] = _u[2]
         nothing
@@ -36,24 +36,24 @@ function no_worldage()
     u = rand(2)
     p = nothing
     t = nothing
-    f1(du,u,p,t)
+    f1(du, u, p, t)
 end
 no_worldage()
 ```
 
 ## Changing how global symbols are looked up
 
 If you want to use helper functions or global variables from a different
-module within your function expression you'll need to pass a `context_module`
+module within your function expression, you'll need to pass a `context_module`
 to the `@RuntimeGeneratedFunction` constructor. For example
 
 ```julia
 RuntimeGeneratedFunctions.init(@__MODULE__)
 
 module A
-    using RuntimeGeneratedFunctions
-    RuntimeGeneratedFunctions.init(A)
-    helper_function(x) = x + 1
+using RuntimeGeneratedFunctions
+RuntimeGeneratedFunctions.init(A)
+helper_function(x) = x + 1
 end
 
 function g()
@@ -66,12 +66,12 @@ end
 
 ## Precompilation and setting the function expression cache
 
-For technical reasons RuntimeGeneratedFunctions needs to cache the function
+For technical reasons, RuntimeGeneratedFunctions needs to cache the function
 expression in a global variable within some module. This is normally
 transparent to the user, but if the `RuntimeGeneratedFunction` is evaluated
 during module precompilation, the cache module must be explicitly set to the
 module currently being precompiled. This is relevant for helper functions in
-some module which construct a RuntimeGeneratedFunction on behalf of the user.
+some module, which construct a RuntimeGeneratedFunction on behalf of the user.
 For example, in the following code, any third party user of
 `HelperModule.construct_rgf()` user needs to pass their own module as the
 `cache_module` if they want the returned function to work after precompilation:
@@ -82,13 +82,13 @@ RuntimeGeneratedFunctions.init(@__MODULE__)
 # Imagine HelperModule is in a separate package and will be precompiled
 # separately.
 module HelperModule
-    using RuntimeGeneratedFunctions
-    RuntimeGeneratedFunctions.init(HelperModule)
+using RuntimeGeneratedFunctions
+RuntimeGeneratedFunctions.init(HelperModule)
 
-    function construct_rgf(cache_module, context_module, ex)
-        ex = :((x)->$ex^2 + x)
-        RuntimeGeneratedFunction(cache_module, context_module, ex)
-    end
+function construct_rgf(cache_module, context_module, ex)
+    ex = :((x) -> $ex^2 + x)
+    RuntimeGeneratedFunction(cache_module, context_module, ex)
+end
 end
 
 function g()
@@ -103,56 +103,72 @@ f = g()
 ```
 
 ## Reproducibility
+
 ```@raw html
 <details><summary>The documentation of this SciML package was built using these direct dependencies,</summary>
 ```
+
 ```@example
 using Pkg # hide
 Pkg.status() # hide
 ```
+
 ```@raw html
 </details>
 ```
+
 ```@raw html
 <details><summary>and using this machine and Julia version.</summary>
 ```
+
 ```@example
 using InteractiveUtils # hide
 versioninfo() # hide
 ```
+
 ```@raw html
 </details>
 ```
+
 ```@raw html
 <details><summary>A more complete overview of all dependencies and their versions is also provided.</summary>
 ```
+
 ```@example
 using Pkg # hide
-Pkg.status(;mode = PKGMODE_MANIFEST) # hide
+Pkg.status(; mode = PKGMODE_MANIFEST) # hide
 ```
+
 ```@raw html
 </details>
 ```
+
 ```@raw html
 You can also download the 
 <a href="
 ```
+
 ```@eval
 using TOML
-version = TOML.parse(read("../../Project.toml",String))["version"]
-name = TOML.parse(read("../../Project.toml",String))["name"]
-link = "https://github.com/SciML/"*name*".jl/tree/gh-pages/v"*version*"/assets/Manifest.toml"
+version = TOML.parse(read("../../Project.toml", String))["version"]
+name = TOML.parse(read("../../Project.toml", String))["name"]
+link = "https://github.com/SciML/" * name * ".jl/tree/gh-pages/v" * version *
+       "/assets/Manifest.toml"
 ```
+
 ```@raw html
 ">manifest</a> file and the
 <a href="
 ```
+
 ```@eval
 using TOML
-version = TOML.parse(read("../../Project.toml",String))["version"]
-name = TOML.parse(read("../../Project.toml",String))["name"]
-link = "https://github.com/SciML/"*name*".jl/tree/gh-pages/v"*version*"/assets/Project.toml"
+version = TOML.parse(read("../../Project.toml", String))["version"]
+name = TOML.parse(read("../../Project.toml", String))["name"]
+link = "https://github.com/SciML/" * name * ".jl/tree/gh-pages/v" * version *
+       "/assets/Project.toml"
 ```
+
 ```@raw html
 ">project</a> file.
-```
+```