🧪 TEST: Make sure documentation links work and point to `latest`

[giovannipizzi]

Since we have changed the documentation, all links are broken.

We should ensure to use the tag v1.3.0 (as soon as it's released) for the links of the current 2020 tutorial (at least).

[mbercx]

Since we want to move to having tutorial material that is always up to date with the latest aiida-core version, we should check that they point to latest, I think.

[giovannipizzi]

On the other end, in practice we'll not manage to keep thing updated, and we've had multiple occasions where links were broken?

[mbercx]

Sorry, I was a little quick in my triage-ing zeal. 😅

We can use intersphinx for links to aiida-core (in fact we already are in many cases). I think we should aim to keep things updated. This was one reason for possibly moving the tutorials into the documentation, to avoid this getting out of sync, and immediately making changes to a tutorial when you open a PR, same as you would for the other docs.

However, I think we can also look into setting up a nightly build versus the latest release for the tutorial materials. Over time we want to leverage the fact that our tutorials will be executable to also test the actual commands, but for now this will already catch broken links if we run with linkcheck (I just found out about this, seems quite useful, not sure if it's complete?):

$ make html linkcheck
sphinx-build -b html -n -d build/doctrees   . build/html
Running Sphinx v3.5.4
make[1]: Nothing to be done for `pre-docs'.

loading pickled environment... done
...
preparing documents... done
writing output... [100%] sections/workflows/writing_basics                                                                                                                        

(sections/data/querying: line  558) ok        https://aiida-tutorials.readthedocs.io/en/latest/pages/2020_Intro_Week/appendices/exploring_provenance.html
(sections/calculations/index: line   39) ok        https://aiida-quantumespresso.readthedocs.io/en/latest/user_guide/get_started/examples/pw_tutorial.html
...
(sections/data/querying: line  439) broken    https://aiida-core.readthedocs.io/en/latest/querying/querybuilder/append.html#joining-entities - 404 Client Error: Not Found for url: https://aiida.readthedocs.io/projects/aiida-core/en/latest/querying/querybuilder/append.html
...
(sections/plugins/index: line    8) redirect  https://www.youtube.com/watch?v=bjTUnHXZ6oY&list=PL19kfLn4sO_-e_A9lVYb_NBNcwoVvUP6V - with Found to https://consent.youtube.com/ml?continue=https://www.youtube.com/watch?v%3DbjTUnHXZ6oY%26list%3DPL19kfLn4sO_-e_A9lVYb_NBNcwoVvUP6V&gl=CH&hl=de&pc=yt&uxe=23983172&src=1
(sections/fundamentals/basics: line    1) redirect  https://youtu.be/vlmjVwGJgEU - with Found to https://consent.youtube.com/ml?continue=https://www.youtube.com/watch?v%3DvlmjVwGJgEU%26feature%3Dyoutu.be&gl=CH&hl=de&pc=yt&uxe=23983172&src=1
build finished with problems.
make: *** [linkcheck] Error 1

If the nightly build catches these errors, I get a ping on slack and fix it. :)

[mbercx]

To reiterate something I've already said in several meetings (but maybe not with you, @giovannipizzi 🙃 ): I think it's mission-critical that the tutorials on the latest page are always up to date with the latest AiiDA release. Not just checked every year we do a tutorial. It's the most important part of the documentation, in my view. As highlighted in the "Documentation system" that we base ourselves on:

"Tutorials are what will turn your learners into users. A bad or missing tutorial will prevent your project from acquiring new users."

Although QM and AiiDAlab are useful tools for organising tutorial events, we should also strive to have AiiDA be as easy to install as possible, so people can run the latest version with tutorials that do not break. Again, from the tutorial document:

"[...] the single most important thing is that what you ask the beginner to do must work. The learner needs to see that the actions you ask them to take have the effect you say they will have."

[giovannipizzi]

I agree - my only comment is that, from experience, it's something very hard to do :-)

[mbercx]

[giovannipizzi]

[mbercx]

Why do I feel I'm going to regret this? 😭

[mbercx]

@giovannipizzi I've added linkcheck to the Sphinx build call in the CI workflow:

https://github.com/aiidateam/aiida-tutorials/blob/2ba4eeae5bfd814d99e280f5526113bf28d825ce/.github/workflows/ci.yml#L42-L43

So this will catch any broken links written in Markdown syntax. intersphinx links (preferred) will be caught by the build as well. However, links written in HTML syntax apparently aren't checked. You can find more info here:

https://github.com/aiidateam/aiida-tutorials/wiki/Moving-to-using-MyST-Markdown#links

Feel free to correct in case you see anything wrong. PS: Have you ever tried something like this:

https://www.drlinkcheck.com/

Or one of the alternatives found here?