Can't build docs locally based on instructions in "Contributor's guide"

[tomchor]

I'm trying to build the docs locally because I want to resolve #1478. I followed the instructions in the docs but I'm not able to generate index.html. Here's a pastebin with the first few errors that appear: https://pastebin.com/25A8SqeX

It looks like the doc generator is comparing the actual output with some expected output? Is that something the docs should do?

Anyway, I've never built julia docs before so I'm kinda unfamiliar with this. Help is appreciated!

[francispoulin]

thanks @tomchor for posting this. I've had difficulties with buildin docs locally as well and am also very curious how one can do this more easily.

[ali-ramadhan]

It looks like the doctests are failing because the output is a bit different, not sure why though.

I guess the fix could be to set these lines

Oceananigans.jl/docs/make.jl

Lines 154 to 155 in 6bfc155

	doctest = true,
	strict = true,

to

 doctest = false, 
  strict = false, 

which should disable doctests (and will build docs even if warnings pop up).

But would be good to figure out why docs don't build nicely locally and make it easier to build docs locally in general.

[francispoulin]

From the experience I have building docs, make.jl makes everything and 'make_example.jl makes one example. However, the latter still builds everything around it. I wonder if we could have something like make_example_only.jl that is very barebones that only makes the example you are doing locally, so you can see how it comes out. I would think this would help with the debugging quite a bit. If this one works, then you could try make_example.jl to see how it fits and then make.jl to get the whole package.

[navidcy]

@tomchor are you running Julia v1.6? Some things with doctests have broken in v1.6... I discovered it the other day while working on #1530. Will try to fix these issues today/tomorrow.

[tomchor]

@navidcy Nope. Using Julia 1.5.4 for this one!

[navidcy]

@navidcy Nope. Using Julia 1.5.4 for this one!

Strange then! I'll dig into this!

[tomchor]

Thanks, @ali-ramadhan, your suggestion seems to work. I was able to compile the docs in my tc/tilted_bbl branch. For some I still couldn't build the docs locally for the tc/simulation_tips branch though. Weird. The process never seemed to complete. I stopped it after literally over an hour:

(base) tomas@np900:~/repos/Oceananigans.jl$ time julia --project=docs/ docs/make.jl
[ Info: generating markdown page from `~/repos/Oceananigans.jl/examples/one_dimensional_diffusion.jl`
[ Info: writing result to `~/repos/Oceananigans.jl/docs/src/generated/one_dimensional_diffusion.md`
[ Info: generating markdown page from `~/repos/Oceananigans.jl/examples/geostrophic_adjustment.jl`
[ Info: writing result to `~/repos/Oceananigans.jl/docs/src/generated/geostrophic_adjustment.md`
[ Info: generating markdown page from `~/repos/Oceananigans.jl/examples/two_dimensional_turbulence.jl`
[ Info: writing result to `~/repos/Oceananigans.jl/docs/src/generated/two_dimensional_turbulence.md`
[ Info: generating markdown page from `~/repos/Oceananigans.jl/examples/internal_wave.jl`
[ Info: writing result to `~/repos/Oceananigans.jl/docs/src/generated/internal_wave.md`
[ Info: generating markdown page from `~/repos/Oceananigans.jl/examples/convecting_plankton.jl`
[ Info: writing result to `~/repos/Oceananigans.jl/docs/src/generated/convecting_plankton.md`
[ Info: generating markdown page from `~/repos/Oceananigans.jl/examples/ocean_wind_mixing_and_convection.jl`
[ Info: writing result to `~/repos/Oceananigans.jl/docs/src/generated/ocean_wind_mixing_and_convection.md`
[ Info: generating markdown page from `~/repos/Oceananigans.jl/examples/langmuir_turbulence.jl`
[ Info: writing result to `~/repos/Oceananigans.jl/docs/src/generated/langmuir_turbulence.md`
[ Info: generating markdown page from `~/repos/Oceananigans.jl/examples/eady_turbulence.jl`
[ Info: writing result to `~/repos/Oceananigans.jl/docs/src/generated/eady_turbulence.md`
[ Info: generating markdown page from `~/repos/Oceananigans.jl/examples/kelvin_helmholtz_instability.jl`
[ Info: writing result to `~/repos/Oceananigans.jl/docs/src/generated/kelvin_helmholtz_instability.md`
[ Info: generating markdown page from `~/repos/Oceananigans.jl/examples/shallow_water_Bickley_jet.jl`
[ Info: writing result to `~/repos/Oceananigans.jl/docs/src/generated/shallow_water_Bickley_jet.md`
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: skipped.
[ Info: ExpandTemplates: expanding markdown templates.
^C
real	78m19.408s
user	77m0.914s
sys	1m2.316s
(base) tomas@np900:~/repos/Oceananigans.jl$ 

[navidcy]

@ali-ramadhan, should we change the instructions in the Contributor's Guide to reflect the way the docs are build post #1573?

[ali-ramadhan]

Ah yes! Seems like we were probably not doing it exactly right before...

We could also add the environment variable JULIA_DEBUG=Documenter if people think it's helpful to get an idea of which example is currently being built (for when you build docs + examples locally).

[navidcy]

Is this still an issue? @tomchor, @ali-ramadhan ?

[tomchor]

I haven't tried it since! Also I'm taking a few days off at the moment, otherwise I'd try it quickly for you.

[navidcy]

No worries! 😉

[navidcy]

I confirm that I can build docs locally using

julia --project=docs/ -e 'using Pkg; Pkg.instantiate()'; julia --project=docs docs/make.jl;