Update documentation formatting and infrastructure (#792)

* Update documentation steps in ci.yml

- Give steps names
- Use `shell:` option for cleaner command specificatiosn

* Update syntax highlight tags in code blocks

`julia` → `julia-repl`

* Update code output in example block

* Add LaTeX `align*` blocks to math formulae in how_it_works.md

Make multi-line formulae appear as intended

* Use `[sources]` section in docs/Project.toml to manage self-dep

* Make simple docs step into one-line in ci.yml

Signed-off-by: abhro <5664668+abhro@users.noreply.github.com>

---------

Signed-off-by: abhro <5664668+abhro@users.noreply.github.com>

Author: abhro

.github/workflows/ci.yml

@@ -61,17 +61,16 @@ jobs:
         with:
           version: '1'
       - uses: julia-actions/cache@v2
-      - run: |
-          julia --project=docs -e '
-            using Pkg
-            Pkg.develop(PackageSpec(path=pwd()))
-            Pkg.instantiate()'
-      - run: |
-          julia --project=docs -e '
-            using Documenter: doctest
-            using ForwardDiff
-            doctest(ForwardDiff)'
-      - run: julia --project=docs docs/make.jl
+      - name: Set up environment
+        run: julia --project=docs -e 'using Pkg; Pkg.instantiate()'
+      - name: Run doctests
+        shell: julia --project=docs {0}
+        run: |
+          using Documenter: doctest
+          using ForwardDiff
+          doctest(ForwardDiff)
+      - name: Build and deploy documentation
+        run: julia --project=docs docs/make.jl
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

docs/Project.toml

@@ -4,3 +4,6 @@ ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
 
 [compat]
 Documenter = "1"
+
+[sources]
+ForwardDiff = {path = ".."}

docs/src/dev/how_it_works.md

@@ -97,30 +97,35 @@ examine the case where the input vector size is 4 and the chunk size is 2. It th
 two calls to ``f`` to evaluate the gradient:
 
 ```math
-\vec{x} = \begin{bmatrix}
+\begin{align*}
+\vec{x} &= \begin{bmatrix}
                x_1 \\
                x_2 \\
                x_3 \\
                x_4
            \end{bmatrix}
 
-\vec{x}_{\epsilon} = \begin{bmatrix}
-                        x_1 + \epsilon_1 \\
-                        x_2 + \epsilon_2 \\
-                        x_3 \\
-                        x_4
-                     \end{bmatrix}
+\\
+
+\vec{x}_{\epsilon} &= \begin{bmatrix}
+                          x_1 + \epsilon_1 \\
+                          x_2 + \epsilon_2 \\
+                          x_3 \\
+                          x_4
+                      \end{bmatrix}
 \to
 f(\vec{x}_{\epsilon}) = f(\vec{x}) + \frac{\delta f(\vec{x})}{\delta x_1} \epsilon_1 + \frac{\delta f(\vec{x})}{\delta x_2} \epsilon_2
-
-\vec{x}_{\epsilon} = \begin{bmatrix}
-                        x_1 \\
-                        x_2 \\
-                        x_3 + \epsilon_1 \\
-                        x_4 + \epsilon_2
-                     \end{bmatrix}
+\\
+
+\vec{x}_{\epsilon} &= \begin{bmatrix}
+                         x_1 \\
+                         x_2 \\
+                         x_3 + \epsilon_1 \\
+                         x_4 + \epsilon_2
+                      \end{bmatrix}
 \to
 f(\vec{x}_{\epsilon}) = f(\vec{x}) + \frac{\delta f(\vec{x})}{\delta x_3} \epsilon_1 + \frac{\delta f(\vec{x})}{\delta x_4} \epsilon_2
+\end{align*}
 ```
 
 This seeding process is similar for Jacobians, so we won't rehash it here.

docs/src/index.md

@@ -8,13 +8,13 @@ While performance can vary depending on the functions you evaluate, the algorith
 
 ForwardDiff is a registered Julia package, so it can be installed by running:
 
-```julia
+```julia-repl
 julia> Pkg.add("ForwardDiff")
 ```
 
 Here's a simple example showing the package in action:
 
-```julia
+```julia-repl
 julia> using ForwardDiff
 
 julia> f(x::Vector) = sin(x[1]) + prod(x[2:end]);  # returns a scalar
@@ -45,7 +45,7 @@ Functions like `f` which map a vector to a scalar are the best case for reverse-
 but ForwardDiff may still be a good choice if `x` is not too large, as it is much simpler.
 The best case for forward-mode differentiation is a function which maps a scalar to a vector, like this `g`:
 
-```julia
+```julia-repl
 julia> g(y::Real) = [sin(y), cos(y), tan(y)];  # returns a vector
 
 julia> ForwardDiff.derivative(g, pi/4)

docs/src/user/advanced.md

@@ -29,7 +29,7 @@ bandwidth.
 
 For example:
 
-```julia
+```julia-repl
 julia> using ForwardDiff: GradientConfig, Chunk, gradient!
 
 # let's use a Rosenbrock function as our target function
@@ -75,7 +75,7 @@ julia> @time gradient!(out, rosenbrock, x, cfg10);
 If you do not explicitly provide a chunk size, ForwardDiff will try to guess one for you
 based on your input vector:
 
-```julia
+```julia-repl
 # The GradientConfig constructor will automatically select a
 # chunk size in one is not explicitly provided
 julia> cfg = ForwardDiff.GradientConfig(rosenbrock, x);
@@ -125,7 +125,7 @@ usually the correct thing to do, but in some cases can erroneously "poison" valu
 aren't sensitive to the input and thus cause ForwardDiff to incorrectly return `NaN` or
 `Inf` derivatives. For example:
 
-```julia
+```julia-repl
 # the dual number's perturbation component is zero, so this
 # variable should not propagate derivative information
 julia> log(ForwardDiff.Dual{:tag}(0.0, 0.0))
@@ -148,7 +148,7 @@ ForwardDiff's `NaN`-safe mode by using the
 [Preferences.jl](https://github.com/JuliaPackaging/Preferences.jl) API to set
 the `nansafe_mode` preference to true, for example via:
 
-```julia
+```julia-repl
 julia> using ForwardDiff, Preferences
 
 julia> set_preferences!(ForwardDiff, "nansafe_mode" => true)
@@ -159,7 +159,7 @@ this preference.
 
 Alternatively, you can set the preference before loading ForwardDiff, for example via:
 
-```julia
+```julia-repl
 julia> using Preferences, UUIDs
 
 julia> set_preferences!(UUID("f6369f11-7733-5829-9624-2563aa707210"), "nansafe_mode" => true)
@@ -180,9 +180,9 @@ While ForwardDiff does not have a built-in function for taking Hessians of vecto
 functions, you can easily compose calls to `ForwardDiff.jacobian` to accomplish this.
 For example:
 
-```julia
+```julia-repl
 julia> ForwardDiff.jacobian(x -> ForwardDiff.jacobian(cumprod, x), [1,2,3])
-9×3 Array{Int64,2}:
+9×3 Matrix{Int64}:
  0  0  0
  0  1  0
  0  3  2
@@ -200,12 +200,12 @@ example, if you require the shape of the output to be a tensor rather than a blo
 you can do so with a `reshape` (note that `reshape` does not copy data, so it's not an
 expensive operation):
 
-```julia
+```julia-repl
 julia> function vector_hessian(f, x)
-       n = length(x)
-       out = ForwardDiff.jacobian(x -> ForwardDiff.jacobian(f, x), x)
-       return reshape(out, n, n, n)
-   end
+           n = length(x)
+           out = ForwardDiff.jacobian(x -> ForwardDiff.jacobian(f, x), x)
+           return reshape(out, n, n, n)
+       end
 vector_hessian (generic function with 1 method)
 
 julia> vector_hessian(cumprod, [1, 2, 3])