Following the ShearBand benchmark documentation page creates error message

[gassmoeller]

Related to openjournals/joss-reviews#9365

After trying to run the provided example files didnt work for me (see #395) I tried following the instructions for the ShearBand benchmark to see if I can reproduce Fig. 3 a) in the paper. I followed these instructions as precisely as possible: https://ptsolvers.github.io/JustRelax.jl/dev/man/ShearBands

Every time I got the package error described in #395 I manually installed the missing packages (Julia didnt actually install them, just activated them I think). When I got to the following lines:

phase_ratios = PhaseRatios(backend, length(rheology), ni)
init_phases!(phase_ratios, xci, radius)

I get the following error message:

ERROR: UndefVarError: `phase_ratios` not defined in `Main`
Suggestion: add an appropriate import or assignment. This global was declared but not assigned.
Stacktrace:
 [1] top-level scope
   @ REPL[33]:1

Is it possible that some line is missing in the instructions?

I generally struggle with the same problem in my projects. A duplication of the code on the documentation page eventually leads to conflicts or outdated code in the documentation, because the original source code is being updated. Ideally one can include the original file into the documentation, or only reproduce the most important lines and otherwise link to the original file. Everything that removes duplication reduces your future maintenance effort. This general comment is not something to address as part of the JOSS review, but maybe some guideline for future additions. But please check if an instruction is missing for the example documentation I listed above.

[albert-de-montserrat]

You are right, the doc page of this example in #main is broken. I fixed it already few weeks ago in #343, the PR corresponding to the JOSS paper, in this commit.

And thanks for your suggestions! Will take them in consideration. There are some nice tools in Julia such as Literate.jl that can for example generate Markdown files from Julia scripts. It may still lead to code duplication, but it would essentially make these doc files testable.

[gassmoeller]

Thanks the changes look good. I was about to close this issue, but I noticed that the development documentation seems to be offline (https://ptsolvers.github.io/JustRelax.jl/dev/ this is the page that you link to from the main repo page). All the pages I linked to above are no longer available. Is there something that changed on your side, or is there a temporary outage of some github pages?

This site is still available: https://ptsolvers.github.io/JustRelax.jl/v0.4.3/

This issue can be closed when the development documentation is again available.

[albert-de-montserrat]

Thanks for reporting it, we bumped the documenter version and we didn't realise the deployment had breaking changes... https://ptsolvers.github.io/JustRelax.jl/dev/ is available again.