Run examples and produce output with every Docs built

[navidcy]

This PR makes code examples in docs run every time the docs are built and, this way, it ensures that the code and output are always current with latest code version.

(Follow up from a discussion in #344.)

[navidcy]

@mortenpi thanks for helping out on Slack for this and pointing out the ansicolor=true kwarg!

Now UnicodePlots works but there are some strange white horizontal lines...

E.g., see how this plot looks like in the docs preview
https://speedyweather.github.io/SpeedyWeather.jl/previews/PR345/how_to_run_speedy/
versus this
https://raw.githubusercontent.com/SpeedyWeather/SpeedyWeather.jl/main/docs/img/barotropic_vorticity.jpg

Any idea what's happening here?

[mortenpi]

We apply 1.5 line height. If I disable that, it looks like this

.. which is great, but it makes normal text output look awful

I don't really have a good solution here though, since there is no way to automatically distinguish these two cases, to apply different CSS to them. Might be worth an issue over at Documenter though.

[mortenpi]

Though, if you don't mind that look for the text blocks, you could apply custom CSS here that overrides the line-height for the output blocks.

[navidcy]

oh I see... gotcha...
well ideally perhaps one would want to disable that for code output only, not for everywhere... OK, I'll post an issue in Documenter!

[milankl]

This is awesome, thanks folks! Another related issue is that some terminals use fewer colours than others. iTerm2 (similar VSCode) left and macos Terminal right

I haven't understood why that is, how to switch been one and the other, or whether it's easy to get the more colours into the Documenter easily - but this would be awesome 😍

[milankl]

(sorry for merging main in here)

@navidcy while the docs build, there is the following error which means that PyPlot figures are not produced and included in the docs. Locally this works fine for me though!

┌ Warning: failed to run `@example` block in src/how_to_run_speedy.md:92-97
│ ```@example howtorun
│ using PyPlot, NCDatasets
│ ioff() # hide
│ ds = NCDataset("run_0001/output.nc");
│ ds["vor"]
│ ```
│   value =
│    InitError: PyCall.PyError("PyImport_ImportModule\n\nThe Python package matplotlib could not be imported by pyimport. Usually this means\nthat you did not install matplotlib in the Python version being used by PyCall.\n\nPyCall is currently configured to use the Python version at:\n\n/usr/bin/python3\n\nand you should use whatever mechanism you usually use (apt-get, pip, conda,\netcetera) to install the Python package containing the matplotlib module.\n\nOne alternative is to re-configure PyCall to use a different Python\nversion on your system: set ENV[\"PYTHON\"] to the path/name of the python\nexecutable you want to use, run Pkg.build(\"PyCall\"), and re-launch Julia.\n\nAnother alternative is to configure PyCall to use a Julia-specific Python\ndistribution via the Conda.jl package (which installs a private Anaconda\nPython distribution), which has the advantage that packages can be installed\nand kept up-to-date via Julia.  As explained in the PyCall documentation,\nset ENV[\"PYTHON\"]=\"\", run Pkg.build(\"PyCall\"), and re-launch Julia. Then,\nTo install the matplotlib module, you can use `pyimport_conda(\"matplotlib\", PKG)`,\nwhere PKG is the Anaconda package that contains the module matplotlib,\nor alternatively you can use the Conda package directly (via\n`using Conda` followed by `Conda.add` etcetera).\n\n", PyCall.PyObject(Ptr{PyCall.PyObject_struct} @0x00007f2d6706a8c0), PyCall.PyObject(Ptr{PyCall.PyObject_struct} @0x00007f2d8f3e1000), PyCall.PyObject(Ptr{PyCall.PyObject_struct} @0x0000000000000000))
│    during initialization of module PyPlot
└ @ Documenter.Expanders ~/.julia/packages/Documenter/bYYzK/src/Utilities/Utilities.jl:34

I guess you are using CairoMakie for Oceananigans?

[milankl]

Locally I get

the build here is however

So even the # hide lines are ignored??

[navidcy]

Locally I get

the build here is however

So even the # hide lines are ignored??

Try #hide instead of # hide.

[milankl]

@navidcy I think I got it working by replacing PyPlot with PythonPlot... @simone-silvestri and I have been trying to use SixelTerm, which actually works too!! I currently just can't get it to work with PyPlot/PythonPlot but Plots.jl works fine - I'm just not as used to that interface.