Broken links in docs

[jl-wynen]

See https://productionresultssa1.blob.core.windows.net/actions-results/974805a3-741b-40fa-be52-ceb4f0c6133d/workflow-job-run-90fef92c-9099-5713-7450-9df0e4201914/logs/job/job-logs.txt?rsct=text%2Fplain&se=2024-12-02T08%3A36%3A48Z&sig=E6AvujU6%2FKlOP%2FTOU%2FUrwnQEuxKR1LGBuqYL09BVFUM%3D&ske=2024-12-02T17%3A56%3A07Z&skoid=ca7593d4-ee42-46cd-af88-8b886a2f84eb&sks=b&skt=2024-12-02T05%3A56%3A07Z&sktid=398a6654-997b-47e9-b12b-9515b896b4de&skv=2024-11-04&sp=r&spr=https&sr=b&st=2024-12-02T08%3A26%3A43Z&sv=2024-11-04

One of the is tricky, it looks like Sphinx pulled in the docstring of scipp.Variable for a domain type. And that docstring has a relative link to a page in the Scipp docs.

[jl-wynen]

I don't see a simple solution to

One of the is tricky, it looks like Sphinx pulled in the docstring of scipp.Variable for a domain type. And that docstring has a relative link to a page in the Scipp docs.

The problem is larger than this. The generated pages for generic domain types (subclasses of sciline.Scope) are pretty bad:

They don't show the base classes but contain a line like DetectorPositionOffset(x: SUPER) which is based on Scope.__new__. It shows SUPER, a TypeVar used by Scope that is not very meaningful in the docs.
In addition, they show the base class' __init__ as well as a list of base class methods. The latter is fine, but the __init__ is not great because we normally don't initialise domain types like this. We use something like DetectorPositionOffset(var) instead.

There are several potential solutions:

• Use a custom class template instead of docs/_templates/class-template.rst. This could produce decent output but it would be difficult to identify base classes in the template. Plus we would need a way to switch to it in place of the default template, but only for domain types.
• Use a custom module template for the types module(s). Same as above, we would need a way to make Sphinx use that instead of the default one. But this may be easier.
• Implement a Sphinx plugin. I tried it briefly but I could not find a good hook where we could customise classes before they are processed by autosummary.