Using dependency package in doctests

[baptnz]

I’ve created a package and successfully pushed CI-Documenter-generated docs on its github page, but I’m having trouble adding doctests. They currently fail because of a mismatch in the output, and I’m not sure how I should resolve it.

Suppose the function I want documented is:

"""
    euler_active(φ::Real, θ::Real, ψ::Real)

3D rotation matrix

- `φ`: Euler angle (longitude, in [0,2π])
- `θ`: Euler angle (colatitude, in [0,2π])
- `ψ`: Euler angle (rotation around z", in [0,2π])

# Examples

```jldoctest
julia> using StaticArrays
julia>  euler_active(π/2,0,0)
3×3 SMatrix{3, 3, Float64, 9} with indices SOneTo(3)×SOneTo(3):
  6.12323e-17  -1.0          0.0
  1.0           6.12323e-17  0.0
 -0.0           0.0          1.0
```

"""
function euler_active(φ, θ, ψ = 0)

    cosφ = cos(φ)
    cosψ = cos(ψ)
    cosθ = cos(θ)
    sinφ = sin(φ)
    sinψ = sin(ψ)
    sinθ = sin(θ)

    # filled by columns
    R = SMatrix{3,3}(
        cosφ * cosθ * cosψ - sinφ * sinψ,
        sinφ * cosθ * cosψ + cosφ * sinψ,
        -sinθ * cosψ,
        -cosφ * cosθ * sinψ - sinφ * cosψ,
        -sinφ * cosθ * sinψ + cosφ * cosψ,
        sinθ * sinψ,
        cosφ * sinθ,
        sinφ * sinθ,
        cosθ,
    )

    return R

end

My package’s main module loads StaticArrays (used throughout), with using StaticArrays, so I never need to prefix its functions.

The error I’m getting on github’s CI side is:

┌ Error: doctest failure in ~/work/CoupledDipole.jl/CoupledDipole.jl/src/Utils.jl:15-22
│ 
│ ```jldoctest
│ julia> using StaticArrays
│ julia>  euler_active(π/2,0,0)
│ 3×3 SMatrix{3, 3, Float64, 9} with indices SOneTo(3)×SOneTo(3):
│   6.12323e-17  -1.0          0.0
│   1.0           6.12323e-17  0.0
│  -0.0           0.0          1.0
│ ```
│ 
│ Subexpression:
│ 
│  euler_active(π/2,0,0)
│ 
│ Evaluated output:
│ 
│ 3×3 StaticArrays.SMatrix{3, 3, Float64, 9} with indices SOneTo(3)×SOneTo(3):
│   6.12323e-17  -1.0          0.0
│   1.0           6.12323e-17  0.0
│  -0.0           0.0          1.0
│ 
│ Expected output:
│ 
│ using StaticArrays
│ 
│   diff =
│    Warning: Diff output requires color.
│    using StaticArrays3×3 StaticArrays.SMatrix{3, 3, Float64, 9} with indices SOneTo(3)×SOneTo(3):
│      6.12323e-17  -1.0          0.0
│      1.0           6.12323e-17  0.0
│     -0.0           0.0          1.0

How should I remedy this? Ideally all docs examples would be run in an environment where StaticArrays is loaded, but I don’t really see where to add this. Also curious about resolving the colour issue.

[mortenpi]

It looks like you’re running into #944. It should be enough if you add

using StaticArrays

at the top of make.jl.

[baptnz]

Thanks – I’m still getting failures though. Do I understand correctly that doctests embedded in the docstrings also get tested outside Documenter’s make.jl process? I can’t work it out but locally

$ julia make.jl 
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.

works fine, while in github’s CI I get all kinds of error when it’s running

Run julia --project=docs -e '
  julia --project=docs -e '
    using Documenter: DocMeta, doctest
    using CoupledDipole
    DocMeta.setdocmeta!(CoupledDipole, :DocTestSetup, :(using CoupledDipole); recursive=true)
    doctest(CoupledDipole)'
  shell: /usr/bin/bash -e {0}
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
┌ Error: doctest failure in ~/work/CoupledDipole.jl/CoupledDipole.jl/src/Materials.jl:182-189

[mortenpi]

Ah, yes, you’re using a separate CI step for doctests which doesn’t use make.jl. You need to add using StaticArrays to the workflow file too, something like:

  julia --project=docs -e '
    using Documenter: DocMeta, doctest
    using StaticArrays
    using CoupledDipole
...

[baptnz]

Thanks – I found this workflow file and added using ... but still no luck

[mortenpi]

What if you also put it into the setdocmeta! call? So have :(using CoupledDipole, StaticArrays) as the third argument?

[baptnz]

Thanks, I think that did it!
I’d tried that by itself earlier, but apparently it was the combination of all the previous tips on this thread that was needed.

Now I just need to figure out how to deal with approximate (floating point) equalities in these tests