Broken link in tmt documentation

[falconizmi]

I found out that the links meant to link to FMF files do not link correctly. Instead of linking to the FMF file, they link to a folder. E.g. here in try documentation the link /tests/try

[qiankehan]

I ran a script to get the broken link for the docs:

for j in $(for i in $(find -name '*html' );do curl localhost:8000/$i |xmllint --xpath '//a' --html -;done 2>/dev/null|grep '\"https://[^\"]*\"' -o|sed 's/\"//g'|sort|uniq);
    do curl -sI $j|head -1|grep -q 404;
    if [ $? -eq 0 ];
        then echo $j ;
    fi ;
done

Results:

https://docs.testing-farm.io/general/0.1/test-request.html
https://docs.testing-farm.io/general/0.1/test-results.html#_tmt_reproducer
https://github.com/teemtee/tmt/tree/main/plans/provision/beaker.fmf
https://github.com/teemtee/tmt/tree/main/tests/execute.fmf
https://github.com/teemtee/tmt/tree/main/tests/execute/reboot.fmf
https://github.com/teemtee/tmt/tree/main/tests/execute/restart.fmf
https://github.com/teemtee/tmt/tree/main/tests/execute/restraint/report_result.fmf
https://github.com/teemtee/tmt/tree/main/tests/execute/result.fmf
https://github.com/teemtee/tmt/tree/main/tests/execute/results-custom.fmf
https://github.com/teemtee/tmt/tree/main/tests/execute/upgrade.fmf
https://github.com/teemtee/tmt/tree/main/tests/login.fmf
https://github.com/teemtee/tmt/tree/main/tests/multihost.fmf
https://github.com/teemtee/tmt/tree/main/tests/plan/import.fmf
https://github.com/teemtee/tmt/tree/main/tests/plan/lint.fmf
https://github.com/teemtee/tmt/tree/main/tests/plans/select.fmf
https://github.com/teemtee/tmt/tree/main/tests/test_convert.fmf
https://github.com/teemtee/tmt/tree/main/tests/try.fmf
https://github.com/teemtee/tmt/tree/main/tests/unit.fmf
https://github.com/teemtee/tmt/tree/main/tmt/id.py
https://github.com/teemtee/tmt/tree/main/tmt/step
https://github.com/teemtee/tmt/tree/main//tmt/steps/provision/localhost.py
https://github.com/teemtee/tmt/tree/main//tmt/steps/provision/vagrant.py
https://tmt.readthedocs.io/en/stable/classes.html#class-conversions

I'd like to fix them

[happz]

@qiankehan FYI, there's a PR to add linkcheck Sphinx engine, https://github.com/teemtee/tmt/pull/2489. It should reveal very similar issues.

Invalid links to tests like the /tests/try.fmf are most likely caused by the template, I'd say it needs to get smarter, because sometimes it is true the verified-by points to an fmf file, and sometimes it does not... See https://github.com/teemtee/tmt/blob/main/docs/templates/story.rst.j2#L203 and https://github.com/teemtee/tmt/blob/main/docs/templates/story.rst.j2#L94.

Maybe we should move the logic mapping links to actual URLs into the Python code in https://github.com/teemtee/tmt/blob/main/docs/scripts/generate-stories.py, as a function, and inject it into the template environment. The function we could then test - I'd worry that by fixing one case we may easily break something else, and unit tests would be very helpful.