Basic: Documenter.jl pages open a local folder

[acroscarrillo]

Hi its me again!

Context:
I have finally a minimal documentation running:

Now I am trying to mimic in exp.jl the lovely documentation of Attractors.jl, in particular the very nice Attractors.jl Tutorial as suggested in this YouTube tutorial.

Issue:
My issue is that if I click here:

My computer opens instead the local folder instead:

I suspect this has to do with how you reference things which apparently I havent figured it out.

Full set of details:
File structure:

── Manifest.toml
── Project.toml 
── docs/
│── Manifest.toml
│── make.jl
│── Project.toml 
│── src/
│ │── index.md
│ │── exp.md    # automatically generated
│ │── experiments/
│ │ │── exp.jl
── src/
│──Test_Module.jl  
│── test.jl

Contents of docs/src/experiments/exp.jl:

# # [exp.jl exp](@id exp)

# ### Test plot

using Plots

plot(rand(100,2))

Contents of docs/make.jl:

# docs/make.jl
push!(LOAD_PATH,"../src/")
using Documenter, Test_Module, Literate

# literate the tutorial
Literate.markdown(
    joinpath(@__DIR__, "src/experiments/", "exp.jl"), joinpath(@__DIR__, "src");
    credit = false
)

makedocs(sitename="My Documentation",
    pages = [
        "index.md",
        "exp.md"
        # "Experiments" => ["experiments/exp_1.md",
                            # "experiments/exp_2.md",
                            # "experiments/exp_3.md",]
    ]
)

Contents of docs/src/index.md:

# Test_Module

´´´@contents
´´´

## Documentation

´´´@meta
CurrentModule = Test_Module
´´´

´´´@autodocs
Modules = [Test_Module]
´´´

## Index

´´´@index
´´´

Question: what is going on?

[goerz]

You have to run a local web server to view the documentation GitHub - JuliaDocs/LiveServer.jl: Simple development server with live-reload capability for Julia. is recommended as a pure-Julia solution, although, if you also have Python, I sometimes find running python -m http.server in the docs/build folder easier.

Another alternative is to use prettyurls=false in the makedocs settings. That would allow you to open any of the .html files directly in a browser, without a web server. However, most people prefer prettyurls=true for when the documentation gets uploaded to, e.g., Github Pages. Some people dynamically switch prettyurls between local and remote builds, but this isn’t recommended. See the warning at Guide · Documenter.jl (scroll down a little bit from that link target):

You may see setups using

makedocs(...,
    format = Documenter.HTML(
        prettyurls = get(ENV, "CI", nothing) == "true"
    )
)

The intent behind this is to use prettyurls=false when building the documentation locally, for easy browsing, and prettyurls=true when deploying the documentation online from GitHub Actions.

However, this is not recommended. For example, if a @raw block references a local image, the correct relative path of that image would depend on the prettyurls setting. Consequently, the documentation might build correctly locally and be broken on Github Actions, or vice versa. It is recommended to always use prettyurls=true and run a local web server to view the documentation.

The note directly above that warning gives some more details about using a web server:

By default, Documenter has pretty URLs enabled, which means that src/foo.md is turned into src/foo/index.html, instead of simply src/foo.html, which is the preferred way when creating a set of HTML to be hosted on a web server.

However, this can be a hindrance when browsing the documentation locally as browsers do not resolve directory URLs like foo/ to foo/index.html for local files. To view the documentation locally, it is recommended that you run a local web server out of the docs/build directory. One way to accomplish this is to install the LiveServer Julia package. You can then start the server with julia -e 'using LiveServer; serve(dir="docs/build")'. Alternatively, if you have Python installed, you can start one with python3 -m http.server --bind localhost.

[acroscarrillo]

That was it! Thank you

For the time being, I am going to use prettyurls=false for the time being and will now be studing how to deploy it on GitHub.