# Testing docs locally with Documenter.jl

**URL:** <https://discourse.julialang.org/t/testing-docs-locally-with-documenter-jl/112371>\
**Category:** General Usage\
**Created:** [April 1, 2024, 8:44am UTC](https://discourse.julialang.org/t/testing-docs-locally-with-documenter-jl/112371 "2024-04-01T08:44:48Z")\
**Posts on this page:** 10\
**Page:** 1

<div class="post-metadata">

**Author:** ![garrek](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/garrek/32/27937_2.png) [@garrek](https://discourse.julialang.org/u/garrek)\
**Post date:** [April 1, 2024, 8:44am UTC](https://discourse.julialang.org/t/testing-docs-locally-with-documenter-jl/112371/1 "2024-04-01T08:44:48Z")

</div>

I’m using Documenter.jl to build my docs for a package. I have a new version of my package on a test branch and I want to build the docs locally. I try to `dev` the local version of the package (on the test branch) but every time I run `julia --project=. make.jl` it “updates” to the released version. Is there a local testing mode or something? I can’t seem to figure out how to do this from the [Documenter.jl website](https://documenter.juliadocs.org/stable/).

(I try to keep a pretty vanilla setup and follow the structure and flow Documenter recommends, like how to set up a make.jl file.)

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [April 1, 2024, 10:48am UTC](https://discourse.julialang.org/t/testing-docs-locally-with-documenter-jl/112371/2 "2024-04-01T10:48:25Z")

</div>

Documenter doesn’t do any package operations so sounds like your setup is a bit strange. What are you doing in `make.jl`? How are you `dev`ing the locally checked out version?

---

<div class="post-metadata">

**Author:** ![ufechner7](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ufechner7/32/51363_2.png) [@ufechner7](https://discourse.julialang.org/u/ufechner7)\
**Post date:** [April 1, 2024, 5:36pm UTC](https://discourse.julialang.org/t/testing-docs-locally-with-documenter-jl/112371/3 "2024-04-01T17:36:41Z")

</div>

Have a look at how we do it with QML.jl:

> **[Developer · QML.jl](https://juliagraphics.github.io/QML.jl/dev/developer/)**
>
> Documentation for QML.jl.

---

<div class="post-metadata">

**Author:** ![garrek](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/garrek/32/27937_2.png) [@garrek](https://discourse.julialang.org/u/garrek)\
**Post date:** [April 1, 2024, 10:07pm UTC](https://discourse.julialang.org/t/testing-docs-locally-with-documenter-jl/112371/4 "2024-04-01T22:07:23Z")

</div>

This is probably where I am misunderstanding Documenter. I am activating my `docs` environment and `dev`ing the local repository. I’m guessing this doesn’t really do anything.

```julia
julia> ]activate docs
julia> dev .

```

My make file is the following. (I am commenting out `deploydocs()` when trying these tests).

```julia
push!(LOAD_PATH, "../src/")

using Documenter, TransferMatrix

makedocs(
    sitename = "TransferMatrix.jl",
    modules = [TransferMatrix],
    pages = [
        "Introduction" => "index.md",
        "Tutorial" => Any[
                    "Quick Start" => "guide/quickstart.md",
                    "Tutorial" => "guide/tutorial.md"
        ],
        "Library" => Any[
                    "Public" => "lib/public.md",
                    "Internals" => "lib/internals.md"
        ],
        "References" => "bibliography.md"
    ]
)

deploydocs(
    repo = "github.com/garrekstemo/TransferMatrix.jl.git",
)

```

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [April 1, 2024, 10:12pm UTC](https://discourse.julialang.org/t/testing-docs-locally-with-documenter-jl/112371/5 "2024-04-01T22:12:32Z")

</div>

> [@garrek](#):
>
> `push!(LOAD_PATH, "../src/")`

This is not needed if you already dev the package. Difficult to tell what goes wrong without concrete code to look at though.

---

<div class="post-metadata">

**Author:** ![garrek](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/garrek/32/27937_2.png) [@garrek](https://discourse.julialang.org/u/garrek)\
**Post date:** [April 1, 2024, 10:18pm UTC](https://discourse.julialang.org/t/testing-docs-locally-with-documenter-jl/112371/6 "2024-04-01T22:18:22Z")

</div>

What other code would be needed to diagnose? There’s only the make.jl file and the commands I’m putting in the terminal, right?

For reference, it’s the “refactor” branch on [TransferMatrix.jl](https://github.com/garrekstemo/TransferMatrix.jl)

---

<div class="post-metadata">

**Author:** ![ufechner7](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ufechner7/32/51363_2.png) [@ufechner7](https://discourse.julialang.org/u/ufechner7)\
**Post date:** [April 1, 2024, 10:23pm UTC](https://discourse.julialang.org/t/testing-docs-locally-with-documenter-jl/112371/7 "2024-04-01T22:23:35Z")

</div>

No reason to activate the docs dir if you have a Project.toml file similar to this one:

> <https://github.com/JuliaGraphics/QML.jl/blob/main/Project.toml>

They point is, Documenter must appear in the [extras] section and in the test target.  
And LiveServer and TestEnv should be installed in the global environment.

Just do:

```julia
using TestEnv; TestEnv.activate()

```

and

```julia
using LiveServer
servedocs()

```

LiveServer will call `make.jl` itself.

Also no need to mess with the LOAD\_PATH and no reason to dev your package for writing the documentation (well, you need to have it checked out with git).

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [April 1, 2024, 10:36pm UTC](https://discourse.julialang.org/t/testing-docs-locally-with-documenter-jl/112371/8 "2024-04-01T22:36:42Z")

</div>

> [@garrek](#):
>
> What other code would be needed to diagnose?

Just something for me to reproduce your problem, because what you are saying you are doing doesn’t match the behavior you are describing as far as I can tell.

> [@garrek](#):
>
> For reference, it’s the “refactor” branch on [TransferMatrix.jl](https://github.com/garrekstemo/TransferMatrix.jl)

Thanks, with that information it was trivial to diagnose; you are using `Pkg` inside of the examples, e.g. here: [https://github.com/garrekstemo/TransferMatrix.jl/blob/ead762de5569c09056377e3681f9dfb3d4c09fc6/docs/src/guide/quickstart.md?plain=1#L28](https://github.com/garrekstemo/TransferMatrix.jl/blob/ead762de5569c09056377e3681f9dfb3d4c09fc6/docs/src/guide/quickstart.md?plain=1#L28) which messes up the environment you have setup beforehand.

Just make these Pkg-blocks raw `julia` code blocks and configure the packages in `docs/Project.toml` before instead.

---

<div class="post-metadata">

**Author:** ![garrek](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/garrek/32/27937_2.png) [@garrek](https://discourse.julialang.org/u/garrek)\
**Post date:** [April 2, 2024, 4:21am UTC](https://discourse.julialang.org/t/testing-docs-locally-with-documenter-jl/112371/9 "2024-04-02T04:21:15Z")

</div>

That is indeed very obvious. I can’t believe I missed that! Thank you for taking a look at the code. Now it builds as expected.

---

<div class="post-metadata">

**Author:** ![garrek](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/garrek/32/27937_2.png) [@garrek](https://discourse.julialang.org/u/garrek)\
**Post date:** [April 2, 2024, 4:22am UTC](https://discourse.julialang.org/t/testing-docs-locally-with-documenter-jl/112371/10 "2024-04-02T04:22:34Z")

</div>

Thank you for the advice and reference materials. I did not know LiveServer would call make.jl.