Testing docs locally with Documenter.jl

General Usage
1

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
2

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?

3

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

2 Likes
4

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

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",
)
5

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

6

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

7

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

and

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

1 Like
8

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.

9

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.

10

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

1 Like