Building docs for the tests

[AdrianSosic]

Should we actually build the docs for our test folder? This could either be done for checking links only, or to actually also publish the generated autodoc on the github.io page. The idea for this was due to a broken link. If we decide not to build it, is there any reason to use refs like :class:... in the first place?

[AVHopp]

If we decide not to build it, there is no need for the links.
Regarding whether the question whether or not to include it in our documentation: What are good practices here? I do not have a strong opinion here, but since a non-developer will probably not really look at the tests, I do not see a large target audience for the generated documentation.

[Scienfitz]

Unless we have a good reason tests should be part of the docs I am not in favor, mainly due to:

Imo there is circular logic here:
What you describe as broken link was nowhere to be rendered in the first place as its part of tests.
So probably this link had no reason to exist in the first place (if this link ends up nowhere other than in the raw code then why put it there in the first place?).
So we wouldn't be talking about how to detect broken links in tests.
So we wouldn't consider adding them to the docs.

Do you see what I mean?

[Scienfitz]

did we agree to not do this and this thread can be closed? @AVHopp @AdrianSosic

[AVHopp]

Iirc, we agreed that this is not important now and that we might want to include this at a later point if we find a reliable way to exclude examples from testing without stuff failing.
So yes, we can close this imo.

[Scienfitz]

are you sure? I'm not sure thats the topic of this thread, this was about adding tests to the docs and not about the examples.

[Scienfitz]

I think you're referring to #69

[AVHopp]

Right, sorry I was being confused. Time for holiday :D