Broken links in the documentation

[jd41]

I write about both of these problems at once because I suspect that they have, in part, the same cause.

I used the tool linkchecker to check the NEST documentation of a ~1-week-old source (commit #4e9a69fab) for broken links:
jd41@pc:~$ sudo apt install linkchecker.

In <install-directory>/share (generated by help_generator?):
jd41@pc:~/nestnew/share$ find .|grep html$|xargs -d '\n' linkchecker --check-extern>linkchecker_installed.txt
Result: linkchecker_installed.txt (66 errors)

In <source-directory>/doc/_build (Sphinx build - doesn't currently get installed?)
jd41@pc:~/nest-simulator/doc/_build$ find .|grep html$|xargs -d '\n' linkchecker --check-extern>linkchecker_sphinx.txt
Result: linkchecker_sphinx.txt (38 errors)

In the help_generator documentation, the majority of cases are links to assumed HTML files in the directory /home/jd41/nestnew/share/doc/nest/help/cc/, which doesn't exist for me (e.g. /home/jd41/nestnew/share/doc/nest/help/cc/spike_generator.html). For the two examples I checked (spike_generator and iaf_psc_alpha), I can't access the corresponding help pages in the NEST SLI interface either. I was able to access them in my last build (from February). Might there be a relation to #1530?

This clearly checks only for links in pre-existing or built HTML files. I know there are some links in ipynb files as well (which I didn't check); I don't know if there are links anywhere else. I can confirm that no additional errors are generated by any HTML files in the whole source directory.

[jd41]

@steffengraber

[terhorstd]

I think this is an important step to the test-ability of documentation. Referential integrity is one point of a list @jessica-mitchell started some time ago. Others were for example: doctests, language linting, doc-style tests (a la PEP8, but for RST), ...
We would have to discuss where/how this fits into a general solution though, and where/when this could best run. There are many aspects to this, therefore I put it into the 'Doc' and 'Infrastructure' teams.

[sarakonradi]

At the NEST Hackathon, we agreed to close this issue and decouple help_generator from link checking. The former will be discussed offline. The latter is addressed in #1907.