search

mxcube / mxcubecore

Backend used by MXCuBE
http://mxcube.github.io/mxcube/
GNU Lesser General Public License v3.0
11 stars 52 forks source link

Set *Sphinx* doc theme to *furo* #810

Closed fabcor-maxiv closed 10 months ago

fabcor-maxiv commented 10 months ago

Set the theme for Sphinx doc to furo: https://pypi.org/project/furo/

Remove the inherited-members setting of autodoc.

fabcor-maxiv commented 10 months ago

Ready for review and merge.

Preview: https://mxcubecore--810.org.readthedocs.build/en/810/

@marcus-oscarsson

rhfogh commented 10 months ago

Looks very nice.

One question, though:

I notice that the class documentation includes all functions - both those defined in the class and those inherited from superclasses. Are we sure that this is what we want - every HardwareObject would replicate quite a lot of inherited functions which somewhat obscures the contents of the specific class? If we do want this, is there a way of separating the inherited from the locally defined methods, properties etc. in separate blocks? Or at least of marking methods so you can see if they are inherited or not?

fabcor-maxiv commented 10 months ago

@rhfogh

I notice that the class documentation includes all functions - both those defined in the class and those inherited from superclasses. Are we sure that this is what we want

Ah... I thought that is what you wanted... Looks like I misunderstood one of your previous messages. :D

I will disable it in a follow-up pull request. As far as I know it is not possible to have special marking for the methods and attributes inherited from base classes.

rhfogh commented 10 months ago

Oops, sorry about that. What I meant (if I am thinking of the right comment) is that there should be links to the super (and maybe be the sub-) classes at the start of the class definition. On balance I'd say that this would be better than either having no reference to the inheritance at all, or having also inherited functions shown in the class body.

But if I have that much influence, maybe I would even have to start proofreading my comments? Oh dear... ;-)

fabcor-maxiv commented 10 months ago

@rhfogh

As far as I understood: the links to the parent classes is a separate setting than the inherited member. So it should be possible to have the former without the latter.

As far as I can tell there is no way to show the list of sub-classes, but I will keep an eye out for this. Maybe I find the right setting or extension to activate.

rhfogh commented 10 months ago

Sounds good. The list of subclasse is, anyway, gravy. The superclasses is the important bit.

Thanks for doing all this work - much appreciated.

fabcor-maxiv commented 10 months ago

I will disable it in a follow-up pull request.

I disabled it in this pull request after all (I usually avoid doing two different things in the same pull request, and changing the scope of the pull request after it has been created): https://github.com/mxcube/mxcubecore/compare/8d502666391589536bb22ffa1a3d9775bd88c6f1..0af18036aec561602d9931b2bc878b1a1aad5230

marcus-oscarsson commented 10 months ago

Thanks !