Testing docs locally with Documenter.jl

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.

(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.)

1 Like

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 deving the locally checked out version?

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


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

julia> ]activate docs
julia> dev .

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

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

using Documenter, TransferMatrix

    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"

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

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

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

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

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:

using TestEnv; TestEnv.activate()


using LiveServer

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).

1 Like

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.

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 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.

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.

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

1 Like