DOC: document onset, duration, description, and ch_names attributes of mne.Annotations

[Famous077]

fixes #12379

What does this implement/fix?

--> I have Converted onset, duration, description, and ch_names from plain
instance attributes to documented properties in mne/annotations.py,
so they appear in the API reference with proper NumPy-style docstrings.

Additional information

--> Even experienced MNE users were unaware these attributes existed because
they did not appear in the generated API documentation. A changelog entry
has been added in doc/changes/dev/12379.other.rst.

[scott-huberty]

@Famous077 can you please sign in to CircleCI via the sign in with Github option? After you do this and push a commit to this branch, the build docs job should run.

[Famous077]

Hi @larsoner @drammock , Changes have been done as per the suggestions. Can you review it whenever you get time. Waiting for your feedback. Hope changes will be helpful for the org.

[drammock]

on main users are free to mutate my_annots.duration pretty freely.. At least compared to the set_annotations route that contains some checks [...] I'm not sure if that was just an oversight. Do we want to be more strict about correctness in these setters, similar to what's done in _check_o_d_s_c_e?

After a real-time chat with @scott-huberty, I think it makes sense to leverage our code in _check_o_d_s_c_e to validate the input to the setters. May require a slight refactor of _check_o_d_s_c_e to avoid duplicating code (so that, e.g., checking descriptions can be done independently of checking onsets, durations, etc)

[drammock]

also, please add closes #12379 to the PR description, so that when this is merged, the motiviating issue will auto-close

[Famous077]

also, please add closes #12379 to the PR description, so that when this is merged, the motiviating issue will auto-close

@drammock , Sorry for the delay, due to exams . Mistakely I mentioned issue number inside the default description template . Now, I have updated accordingly.

[scott-huberty]

@drammock ready for you to take a final review.

[Famous077]

Hi @drammock , I have addressed all the suggestions given. Can you review it whenever you get time. Waiting for your feedback.

[drammock]

jointly reviewed with @scott-huberty

[Famous077]

Hi @drammock , Hi, I've implemented the required changes as per the suggestions. Could you please review the PR when you get a chance and let me know if anything needs to be updated or improved. Thank you

[Famous077]

Hi @larsoner , This PR has been in pending state since last month, Can you review whenever you get time.

[larsoner]

I'd rather let @scott-huberty or @drammock look since they've already been thinking about this!

[cbrnr]

Hello @Famous077! I've added some commits to get this PR merged (please check if these are OK for you, there was one critical missing length check for ch_names). IMO this is now ready for merge as all comments have been addressed. @scott-huberty and @drammock OK for you?

[cbrnr]

Not sure what the problem with the CircleCI docs preview is though...

[tsbinns]

@cbrnr Looks like the same thing that was happening here, where it thinks it's trying to build stable docs so just exits: #13846 (comment)

@drammock @larsoner Was there any headway on figuring out how to sort this?

[larsoner]

CircleCI links to https://app.circleci.com/jobs/github/Famous077/mne-python/280 so the builds are happening in the fork rather than our org. I think @Famous077 disabling builds for the fork on the CircleCI interface would probably fix it. In the meantime I'd recommend building the docs locally and looking

[cbrnr]

Thanks! OT, but I don't like a core service failing because a contributor must first configure something or is not logged in (as a side note, I've never been able to restart a job even though I am logged in, but I seem to have two accounts connected to my email, which is also very confusing). I suggest that we try to fix this on our side, or consider moving to a different service with better GitHub integration.

[drammock]

I suggest that we try to fix this on our side, or consider moving to a different service with better GitHub integration.

happy to entertain alternatives if someone can do the research. IIRC, netlify is awful and GHA has no way of serving the built artifact for inspection, so RTD is the only one I know of that might be worth exploring. But maybe there are others I haven't heard of.

[cbrnr]

netlify is awful

Yes, I would also avoid Netlify.

GHA has no way of serving the built artifact for inspection

It might be possible with a gh-pages branch, but I'm not sure. Something like https://github.com/mmkal/artifact.ci maybe, although probably not exactly this because of potential costs that the developer might charge, but we can always roll our own solution.

so RTD is the only one I know of that might be worth exploring

I use RTD for my projects and I'm very happy. Building and serving pretty much works out of the box, and I've never had any problems. Their build infrastructure is probably not as powerful, so we'd have to check how long the build process actually takes on their site.

[larsoner]

I opened #13930 for further CircleCI / docs discussion

In the meantime @tsbinns @scott-huberty @drammock thoughts on the PR contents since you've commented previously?