mitre/menelaus

Reorganize the class members in the sphinx docs

tms-bananaquit opened this issue · 0 comments

It really seems like there ought to be a clear distinction between attributes, properties, and functions on RTD. The current settings for sphinx don't accomplish this.

In particular, drift_state, total_samples, samples_since_reset are common across all detectors, but to get them to display as inherited using the :inherit-members: option in sphinx, it was necessary to set them up as properties. Only drift_state really needs the validation enabled by the @property decorator, though.

The choice was between two evils: 2 of the 3 appearing in Attributes, redundantly specified in the child classes; or all 3 appearing as properties, documented only in the parents in drift_detector.

If there's a way around this that avoids static .rst files, that'd be fantastic. Otherwise, we may someday have to bite the bullet of maintaining those.

One option for ordering them in a particular way is to use the "member-order":"bysource" option in conf.py, so they'll be ordered according to the source code (seems easy to mess up!), but this still keeps the inherited properties at the bottom, so it's not a big potential improvement over groupwise at the moment.