Don't use the Module(...) constructor to create a module (#2683)

Author: asinghvi17

CHANGELOG.md

@@ -20,6 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+* Modules for `@example` environments are now generated by `eval`'ing an expression, rather than invoking the `Module` constructor, which is not recommended. (#2683)
 * Changed the header crossref step to eagerly fail when encountering a non-unique header slug. ([#2668], [#2787])
 
   This is **potentially breaking** and may cause some documentation builds to fail.
@@ -2153,6 +2154,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#2662]: https://github.com/JuliaDocs/Documenter.jl/issues/2662
 [#2668]: https://github.com/JuliaDocs/Documenter.jl/issues/2668
 [#2674]: https://github.com/JuliaDocs/Documenter.jl/issues/2674
+[#2683]: https://github.com/JuliaDocs/Documenter.jl/issues/2683
 [#2675]: https://github.com/JuliaDocs/Documenter.jl/issues/2675
 [#2676]: https://github.com/JuliaDocs/Documenter.jl/issues/2676
 [#2682]: https://github.com/JuliaDocs/Documenter.jl/issues/2682

src/utilities/utilities.jl

@@ -628,12 +628,19 @@ function get_sandbox_module!(meta, prefix, name = nothing; share_default_module
     # Either fetch and return an existing sandbox from the meta dictionary (based on the generated name),
     # or initialize a new clean one, which gets stored in meta for future re-use.
     return get!(meta, sym) do
-        # If the module does not exists already, we need to construct a new one.
-        m = Module(sym)
-        # eval(expr) is available in the REPL (i.e. Main) so we emulate that for the sandbox
-        Core.eval(m, :(eval(x) = Core.eval($m, x)))
-        # modules created with Module() does not have include defined
-        Core.eval(m, :(include(x) = Base.include($m, abspath(x))))
+        # If the module does not exist already, we need to construct a new one.
+        # We create a baremodule so that we can insert a custom `include` method
+        # that is closer to the one in Main, in that it works relative to the
+        # current working directory, not relative to the module.
+        m = Core.eval(
+            Main, :(
+                baremodule $sym
+                using Base
+                eval(x) = Core.eval($sym, x)
+                include(x) = Base.include($sym, abspath(x))
+                end
+            )
+        )
         return m
     end
 end