Fix LiveServer instructions in dev docs

[clizbe]

Description

Following the instructions did not work for me.
I was eventually able to get LiveServer to generate the docs, but then they would not update with changes.

Validation and testing

No response

Motivation

No response

Target audience

Future devs

Can you help?

I can update the docs once I'm shown how to do it properly.
I tried multiple adjustments to fix it, but couldn't figure it out.

[datejada]

@clizbe, maybe we can reproduce your error together since the instructions and the LiveServer work fine for me. It might be that something is missing there or that some extra hints are missing.

[clizbe]

• In pwsh run:
  julia
pkg> add Revise

• Then return to pwsh and run:
  julia --project=docs

• Note that at this point, running
  pwd()
  shows:
  "C:\Users\clisbyle\OneDrive - TNO\GitHub\TulipaEnergyModel.jl"
  (Doesn't say docs)

Then running pkg> dev . gives this output:

• Then run:
  julia> using LiveServer

Which at least successfully launched the docs.
But I tried making a change and got this error:

Maybe it's a problem with Revise (not global?) or that I'm not in root when I'm launching from pwsh?

[clizbe]

I tried going back to Julia and saying:
using Revise
but when I delete the build folder and rerun servedocs I still get the error when I make changes.

[datejada]

@clizbe have you tried launching pwsh from the root of the TulipaEnergyModel.jl folder rather than the docs folder? if so, do you still have the same error? What I do is to run from there as in the documentation, and get no error, but maybe is not clear from there where the user need to launch the pwsh:

[abelsiqueira]

@datejada, I think @clizbe is running from the root folder.

@clizbe, you forgot one command in the description, but I think you ran it: servedocs(launch_browser=true). Can you confirm that it ran and opened the browser? Or did it error?

Do you have Revise installed globally? Check with pkg> activate and pkg> status.

Does the following works:

# new julia
julia> activate docs # or julia --project=docs
julia> using Revise # should have been installed globally
julia> using LiveServer
julia> servedocs(launch_browser=true)
# modify docs/src/index.md and save
# A bunch of Info and Warning messages, eventually HTMLWriter does its thing and page changes

There will be Warning messages, but it should still work. The warning I see in your post are fine, but it is lacking the normal building stuff, which I guess is related to Revise (in the sense that Revise is not active, so there are no changes, so there is no build to be done).

[clizbe]

@abelsiqueira
Yes I forgot to say I did servedocs(launch_browser=true) and it launches the browser with the dev docs, but if I change anything and save, then the webpage errors and the terminal gives that error message.

Checking activate and status on both my docs env and my global julia shows I have Revise installed.

Running julia> activate docs produces an "extra tokens after end of expression" error.

So I tried:

# close pwsh and start a new one for safety
pwsh> julia --project=docs
julia> using Revise
julia> using LiveServer
julia> servedocs(launch_browser=true)

Caused this error:

So I deleted the build folder and reran servedoces(launch_browser=true) and it launches the browser with the docs.

But if I change anything (I typed "boop" in the a paragraph and hit Ctrl+S) then I get this terminal error:

And the webpage shows:

[datejada]

@clizbe, I have no idea. I don't have those problems 😢 I can even change the docs, and it updates them without problem, unless I type something that causes an error. Even then, if I fix it, it shows the docs correctly rendered again.

Anyway, I think the instructions in the documentation are correct. But if we figure out what is causing your problem, we can add some extra information to the docs for users who might encounter the same problem in the future.

[abelsiqueira]

From the first error message, it looks like you have permission errors, which probably relates to the bigger issue. You shouldn't have to delete the build folder.
So it might be related to Julia or to the terminal pwsh that you're using.

Are you opening pwsh from within VSCode?
If not, can you try that.
If you are, can you try the other terminals?

@gnawin, I vaguely remember you saying something about VSCode permissions, but maybe I'm "hallucinating."

I'm not fluent in Windows permissions, so I'm not sure how to proceed. On Linux/Mac, I would check the permissions of the Julia folder ($HOME/.julia) and the juliaup folder ($HOME/.juliaup), and of the TulipaEnergyModel folder. Path might differ on Windows.

[clizbe]

So one thing I discovered is that Julia does not exist at:
C:\Users<your_username>\AppData\Local\Programs\Julia-x.x.x
And I couldn't find where it's installed.
Maybe I need to find it and then add its bin as a variable in path?

I tried launching Julia from the app, running as administrator.

# I tried navigating to the Tulipa project docs folder... Dunno how this works with dev, branches, etc.
julia> pwd()
"C:\\Users\\clisbyle\\OneDrive - TNO\\GitHub\\TulipaEnergyModel.jl\\docs"

julia> using Revise

julia> using LiveServer

julia> servedocs(launch_browser=true)
ERROR: I didn't find a docs/ or docs/src/ folder.

# Okay, so I tried going to just the TEM project so it can find the subfolder...

julia> cd("C:\\Users\\clisbyle\\OneDrive - TNO\\GitHub\\TulipaEnergyModel.jl")

julia> servedocs(launch_browser=true)
ERROR: LoadError: ArgumentError: Package Documenter not found in current path.
# Makes sense, since it's looking at the Project.toml of TEM and not TEM/docs

[clizbe]

Also, when Julia launches, it tells me to run juliaup update to update my Julia, but that command doesn't work - it's not recognized.

Looks like Julia is located here:

I added this bin to my path, but doesn't help.

I uninstalled and reinstalled both GitBash (it was having a weird error, but it remained after reinstall) and Julia - since my juliaup doesn't work. Still doesn't work. Also, my .julia folder still shows the last modified date as 3/3/2025 which I thought was weird if I just reinstalled it.

[abelsiqueira]

To use LiveServer, you have to:

• Open Julia at (or navigate to) the root of the project
• Activate the docs folder

This means, you are in one folder (root) and activates the other (root/docs). In your post above, there is no activate or --project= indication, so that is the problem there. But it was working before, so that is not the main issue.

Re:

Are you opening pwsh from within VSCode?
If not, can you try that.
If you are, can you try the other terminals?

Have you tried running from VSCode?

Were you always running in adm mode?

Please also reinstall juliaup. How are you installing it? And the .julia folder has to be manually deleted if you want a fresh start - this also implies you have to reinstall all global packages and reinstantiate everything. That being said, it doesn't look like the problem is here. And it looks like Julia is in the correct place for a juliaup installation, no it doesn't look like a path problem.

[clizbe]

I was running everything in VSCode (pwsh because gitbash is broken) until that last try in admin mode. That was in cmd.

I'll try reinstalling juliaup. Thanks!

[clizbe]

I also checked my permissions on both the julia folder structure and the AppData folder (where Python lives but not Julia). And I have access everywhere. Haven't found anywhere yet that I don't have access.

[clizbe]

I'm not sure what it means to be in root. I think it just mean the default when I open the project, aka blah/blah/TulipaEnergyModel.jl?

[clizbe]

Could the problem be that my GitHub folder that holds all my local repos is on OneDrive - so sort of a cloud-sync version that maybe has access issues? 🤔

[clizbe]

Yup I think the problem is that my GitHub folder is on the TNO OneDrive. So I can delete things, but VSCode (or whatever program) cannot. So it can't delete the build folder.
I'm moving my GitHub folder to my local PC to see if that fixes it. Kinda silly to have it on OneDrive anyway since Git takes care of everything except local unsaved work.

[clizbe]

@abelsiqueira
So moving my GitHub folder to my local machine seems to have helped, but it still doesn't work.

Now it seems not to have any issues, but it doesn't open the browser.

I tried fixing the warning about repolink, but it doesn't fix it (and it's just a warning anyway).