search

scipp / sciline

Build scientific pipelines for your data
https://scipp.github.io/sciline/
BSD 3-Clause "New" or "Revised" License
10 stars 2 forks source link

hard to read docs for domain types #143

Open jl-wynen opened 8 months ago

jl-wynen commented 8 months ago

The docs that Sphinx renders for domain types are not the most useful. They simply show the docs of the underlying class. This is a bit hard to read. And it can lead to problems with links, see https://github.com/scipp/essdiffraction/pull/43/commits/8a22410fb9086a09b256c125f662b301a4ae6986

I suggest we simply show the underlying type with a link to its docs. This may be easy to do with a custom template. But only if we keep domain types in a common module. Otherwise, it's hard to detect what are domain types and what not.

SimonHeybrock commented 8 months ago

Isn't this improved with Python 3.10?

jl-wynen commented 8 months ago

How so? Why would this change how Sphinx renders classes?

SimonHeybrock commented 8 months ago

Because NewType was changed to a class instead of a function with 3.10.

jl-wynen commented 8 months ago

I found this in ESSdiffraction (see link) and I built the docs with 3.10. So it may be the other way around, because NewType is a class, sphinx shows the docs for the underlying class.