Add AbstractAlgebra.doctestsetup() helper and use it, then regenerate doctests so they benefit from @show_name

.github/workflows/CI.yml

@@ -66,7 +66,7 @@ jobs:
             Pkg.instantiate()
             using Documenter
             using AbstractAlgebra
-            DocMeta.setdocmeta!(AbstractAlgebra, :DocTestSetup, :(using AbstractAlgebra); recursive = true)
+            DocMeta.setdocmeta!(AbstractAlgebra, :DocTestSetup, AbstractAlgebra.doctestsetup(); recursive = true)
             doctest(AbstractAlgebra)'
       - name: "Process code coverage"
         uses: julia-actions/julia-processcoverage@v1

docs/make.jl

@@ -4,7 +4,8 @@ using Documenter, AbstractAlgebra
 # because we want to force that each jldoctest has its individual
 # `setup = :(using AbstractAlgebra)`.
 # The reason is that the AbstractAlgebra doctests are run also in Nemo,
-# where `using AbstractAlgebra` is deliberately avoided.
+# where `using AbstractAlgebra` must be avoided, as a few symbols change
+# their meaning, e.g. `QQ`.
 
 makedocs(
          format = Documenter.HTML(;

docs/src/assertions.md

@@ -1,11 +1,10 @@
-# Assertion and Verbosity Macros
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = quote
-    using AbstractAlgebra
-end
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
+# Assertion and Verbosity Macros
+
 We describe here various macros provided by AbstractAlgebra.
 
 ## Verbosity macros

docs/src/direct_sum.md

@@ -1,8 +1,6 @@
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = quote
-    using AbstractAlgebra
-end
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Direct Sums
@@ -45,7 +43,7 @@ julia> m2 = F(BigInt[9, 7, -2, 2, -4])
 (9, 7, -2, 2, -4)
 
 julia> S1, f1 = sub(F, [m1, m2])
-(Submodule over integers with 2 generators and no relations, Hom: submodule over integers with 2 generators and no relations -> free module of rank 5 over integers)
+(Submodule over integers with 2 generators and no relations, Hom: S1 -> F)
 
 julia> m1 = F(BigInt[3, 1, 7, 7, -7])
 (3, 1, 7, 7, -7)
@@ -54,7 +52,7 @@ julia> m2 = F(BigInt[-8, 6, 10, -1, 1])
 (-8, 6, 10, -1, 1)
 
 julia> S2, f2 = sub(F, [m1, m2])
-(Submodule over integers with 2 generators and no relations, Hom: submodule over integers with 2 generators and no relations -> free module of rank 5 over integers)
+(Submodule over integers with 2 generators and no relations, Hom: S2 -> F)
 
 julia> m1 = F(BigInt[2, 4, 2, -3, -10])
 (2, 4, 2, -3, -10)
@@ -63,10 +61,10 @@ julia> m2 = F(BigInt[5, 7, -6, 9, -5])
 (5, 7, -6, 9, -5)
 
 julia> S3, f3 = sub(F, [m1, m2])
-(Submodule over integers with 2 generators and no relations, Hom: submodule over integers with 2 generators and no relations -> free module of rank 5 over integers)
+(Submodule over integers with 2 generators and no relations, Hom: S3 -> F)
 
 julia> D, f = direct_sum(S1, S2, S3)
-(DirectSumModule over integers, AbstractAlgebra.Generic.ModuleHomomorphism{BigInt}[Hom: submodule over integers with 2 generators and no relations -> DirectSumModule, Hom: submodule over integers with 2 generators and no relations -> DirectSumModule, Hom: submodule over integers with 2 generators and no relations -> DirectSumModule], AbstractAlgebra.Generic.ModuleHomomorphism{BigInt}[Hom: DirectSumModule -> submodule over integers with 2 generators and no relations, Hom: DirectSumModule -> submodule over integers with 2 generators and no relations, Hom: DirectSumModule -> submodule over integers with 2 generators and no relations])
+(DirectSumModule over integers, AbstractAlgebra.Generic.ModuleHomomorphism{BigInt}[Hom: S1 -> D, Hom: S2 -> D, Hom: S3 -> D], AbstractAlgebra.Generic.ModuleHomomorphism{BigInt}[Hom: D -> S1, Hom: D -> S2, Hom: D -> S3])
 ```
 
 ## Functionality for direct sums
@@ -93,7 +91,7 @@ julia> m2 = F(BigInt[9, 7, -2, 2, -4])
 (9, 7, -2, 2, -4)
 
 julia> S1, f1 = sub(F, [m1, m2])
-(Submodule over integers with 2 generators and no relations, Hom: submodule over integers with 2 generators and no relations -> free module of rank 5 over integers)
+(Submodule over integers with 2 generators and no relations, Hom: S1 -> F)
 
 julia> m1 = F(BigInt[3, 1, 7, 7, -7])
 (3, 1, 7, 7, -7)
@@ -102,7 +100,7 @@ julia> m2 = F(BigInt[-8, 6, 10, -1, 1])
 (-8, 6, 10, -1, 1)
 
 julia> S2, f2 = sub(F, [m1, m2])
-(Submodule over integers with 2 generators and no relations, Hom: submodule over integers with 2 generators and no relations -> free module of rank 5 over integers)
+(Submodule over integers with 2 generators and no relations, Hom: S2 -> F)
 
 julia> m1 = F(BigInt[2, 4, 2, -3, -10])
 (2, 4, 2, -3, -10)
@@ -111,10 +109,10 @@ julia> m2 = F(BigInt[5, 7, -6, 9, -5])
 (5, 7, -6, 9, -5)
 
 julia> S3, f3 = sub(F, [m1, m2])
-(Submodule over integers with 2 generators and no relations, Hom: submodule over integers with 2 generators and no relations -> free module of rank 5 over integers)
+(Submodule over integers with 2 generators and no relations, Hom: S3 -> F)
 
 julia> D, f = direct_sum(S1, S2, S3)
-(DirectSumModule over integers, AbstractAlgebra.Generic.ModuleHomomorphism{BigInt}[Hom: submodule over integers with 2 generators and no relations -> DirectSumModule, Hom: submodule over integers with 2 generators and no relations -> DirectSumModule, Hom: submodule over integers with 2 generators and no relations -> DirectSumModule], AbstractAlgebra.Generic.ModuleHomomorphism{BigInt}[Hom: DirectSumModule -> submodule over integers with 2 generators and no relations, Hom: DirectSumModule -> submodule over integers with 2 generators and no relations, Hom: DirectSumModule -> submodule over integers with 2 generators and no relations])
+(DirectSumModule over integers, AbstractAlgebra.Generic.ModuleHomomorphism{BigInt}[Hom: S1 -> D, Hom: S2 -> D, Hom: S3 -> D], AbstractAlgebra.Generic.ModuleHomomorphism{BigInt}[Hom: D -> S1, Hom: D -> S2, Hom: D -> S3])
 
 julia> summands(D)
 3-element Vector{AbstractAlgebra.Generic.Submodule{BigInt}}:

docs/src/euclidean_interface.md

@@ -1,6 +1,6 @@
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = :(using AbstractAlgebra)
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Euclidean Ring Interface

docs/src/finfield.md

@@ -1,8 +1,6 @@
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = quote
-    using AbstractAlgebra
-end
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Finite fields

docs/src/fraction.md

@@ -1,8 +1,6 @@
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = quote
-    using AbstractAlgebra
-end
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Generic fraction fields

docs/src/fraction_interface.md

@@ -1,8 +1,6 @@
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = quote
-    using AbstractAlgebra
-end
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Fraction Field Interface

docs/src/free_associative_algebra.md

@@ -1,8 +1,6 @@
 ```@meta
 CurrentModule = AbstractAlgebra.Generic
-DocTestSetup = quote
-    using AbstractAlgebra
-end
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Free algebras
@@ -77,7 +75,7 @@ julia> R, (x, y, z) = free_associative_algebra(ZZ, [:x, :y, :z])
 (Free associative algebra on 3 indeterminates over integers, AbstractAlgebra.Generic.FreeAssociativeAlgebraElem{BigInt}[x, y, z])
 
 julia> B = MPolyBuildCtx(R)
-Builder for an element of free associative algebra
+Builder for an element of R
 
 julia> push_term!(B, ZZ(1), [1,2,3,1]); push_term!(B, ZZ(2), [3,3,1]); finish(B)
 x*y*z*x + 2*z^2*x

docs/src/free_module.md

@@ -1,8 +1,6 @@
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = quote
-    using AbstractAlgebra
-end
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Free Modules and Vector Spaces

docs/src/function_field.md

@@ -1,8 +1,6 @@
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = quote
-    using AbstractAlgebra
-end
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Rational function fields
@@ -236,7 +234,7 @@ julia> R1, x1 = rational_function_field(QQ, "x1") # characteristic 0
 (Rational function field over rationals, x1)
 
 julia> U1, z1 = R1["z1"]
-(Univariate polynomial ring in z1 over rational function field, z1)
+(Univariate polynomial ring in z1 over R1, z1)
 
 julia> f = (x1^2 + 1)//(x1 + 1)*z1^3 + 4*z1 + 1//(x1 + 1)
 (x1^2 + 1)//(x1 + 1)*z1^3 + 4*z1 + 1//(x1 + 1)
@@ -257,7 +255,7 @@ julia> R2, x2 = rational_function_field(GF(23), "x1") # characteristic p
 (Rational function field over finite field F_23, x1)
 
 julia> U2, z2 = R2["z2"]
-(Univariate polynomial ring in z2 over rational function field, z2)
+(Univariate polynomial ring in z2 over R2, z2)
 
 julia> g = z2^2 + 3z2 + 1
 z2^2 + 3*z2 + 1
@@ -285,7 +283,7 @@ julia> R, x = rational_function_field(GF(23), :x) # characteristic p
 (Rational function field over finite field F_23, x)
 
 julia> U, z = R[:z]
-(Univariate polynomial ring in z over rational function field, z)
+(Univariate polynomial ring in z over R, z)
 
 julia> g = z^2 + 3z + 1
 z^2 + 3*z + 1
@@ -361,7 +359,7 @@ julia> R, x = rational_function_field(QQ, :x)
 (Rational function field over rationals, x)
 
 julia> U, z = R[:z]
-(Univariate polynomial ring in z over rational function field, z)
+(Univariate polynomial ring in z over R, z)
 
 julia> g = z^2 + 3*(x + 1)//(x + 2)*z + 1
 z^2 + (3*x + 3)//(x + 2)*z + 1
@@ -424,7 +422,7 @@ julia> R, x = rational_function_field(QQ, :x)
 (Rational function field over rationals, x)
 
 julia> U, z = R[:z]
-(Univariate polynomial ring in z over rational function field, z)
+(Univariate polynomial ring in z over R, z)
 
 julia> g = z^2 + 3*(x + 1)//(x + 2)*z + 1
 z^2 + (3*x + 3)//(x + 2)*z + 1

docs/src/functional_map.md

@@ -1,8 +1,6 @@
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = quote
-    using AbstractAlgebra
-end
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Functional maps

docs/src/ideal.md

@@ -1,8 +1,6 @@
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = quote
-    using AbstractAlgebra
-end
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Ideal functionality

docs/src/integer.md

@@ -1,8 +1,6 @@
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = quote
-    using AbstractAlgebra
-end
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Integer ring

docs/src/laurent_mpolynomial.md

@@ -1,8 +1,6 @@
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = quote
-    using AbstractAlgebra
-end
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Sparse distributed multivariate Laurent polynomials

docs/src/laurent_polynomial.md

@@ -1,8 +1,6 @@
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = quote
-    using AbstractAlgebra
-end
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Generic Laurent polynomials

docs/src/map_cache.md

@@ -1,8 +1,6 @@
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = quote
-    using AbstractAlgebra
-end
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Cached maps

docs/src/map_interface.md

@@ -1,8 +1,6 @@
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = quote
-    using AbstractAlgebra
-end
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Map Interface

docs/src/map_with_inverse.md

@@ -1,8 +1,6 @@
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = quote
-    using AbstractAlgebra
-end
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Map with inverse

docs/src/matrix.md

@@ -1,8 +1,6 @@
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = quote
-    using AbstractAlgebra
-end
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Matrix functionality
@@ -836,7 +834,7 @@ julia> K, = residue_field(R, x^3 + 3x + 1); a = K(x);
 
 julia> S = matrix_space(K, 3, 3)
 Matrix space of 3 rows and 3 columns
-  over residue field of univariate polynomial ring modulo x^3 + 3*x + 1
+  over residue field of R modulo x^3 + 3*x + 1
 
 julia> A = S([K(0) 2a + 3 a^2 + 1; a^2 - 2 a - 1 2a; a^2 - 2 a - 1 2a])
 [      0   2*x + 3   x^2 + 1]
@@ -873,7 +871,7 @@ julia> K, = residue_field(R, x^3 + 3x + 1); a = K(x);
 
 julia> S = matrix_space(K, 3, 3)
 Matrix space of 3 rows and 3 columns
-  over residue field of univariate polynomial ring modulo x^3 + 3*x + 1
+  over residue field of R modulo x^3 + 3*x + 1
 
 julia> M = S([K(0) 2a + 3 a^2 + 1; a^2 - 2 a - 1 2a; a^2 + 3a + 1 2a K(1)])
 [            0   2*x + 3   x^2 + 1]
@@ -996,7 +994,7 @@ julia> K, = residue_field(R, x^3 + 3x + 1); a = K(x);
 
 julia> S = matrix_space(K, 3, 3)
 Matrix space of 3 rows and 3 columns
-  over residue field of univariate polynomial ring modulo x^3 + 3*x + 1
+  over residue field of R modulo x^3 + 3*x + 1
 
 julia> A = S([K(0) 2a + 3 a^2 + 1; a^2 - 2 a - 1 2a; a^2 + 3a + 1 2a K(1)])
 [            0   2*x + 3   x^2 + 1]

docs/src/matrix_algebras.md

@@ -1,8 +1,6 @@
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = quote
-    using AbstractAlgebra
-end
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Generic matrix algebras

docs/src/matrix_interface.md

@@ -1,8 +1,6 @@
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = quote
-    using AbstractAlgebra
-end
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Matrix Interface

docs/src/misc.md

@@ -1,8 +1,6 @@
 ```@meta
 CurrentModule = AbstractAlgebra
-DocTestSetup = quote
-    using AbstractAlgebra
-end
+DocTestSetup = AbstractAlgebra.doctestsetup()
 ```
 
 # Miscellaneous