Fix: groups.py doctest fixes

[ljwoods2]

Fixes #3925 in part

Changes made in this Pull Request:

• Fixed all failing doctests in groups.py using sphinx directives
• Updated groups.py with Black formatting

Note: These tests will not pass using "pytest -v --disable-pytest-warnings --doctest-modules " since I used sphinx directives to allow for concise example code. This can be changed but the documentation will become more verbose.

PR Checklist

• Tests?
• Docs?
• CHANGELOG updated?
• Issue raised/referenced?

Developers certificate of origin

• I certify that this contribution is covered by the LGPLv2.1+ license as defined in our LICENSE and adheres to the Developer Certificate of Origin.

---

📚 Documentation preview 📚: https://mdanalysis--4374.org.readthedocs.build/en/4374/

[pep8speaks]

Hello @ljwoods2! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

• In the file package/MDAnalysis/core/groups.py:

Line 1279:80: E501 line too long (82 > 79 characters)
Line 1280:80: E501 line too long (82 > 79 characters)
Line 1281:80: E501 line too long (82 > 79 characters)
Line 1282:80: E501 line too long (82 > 79 characters)
Line 1283:80: E501 line too long (82 > 79 characters)
Line 3068:80: E501 line too long (80 > 79 characters)
Line 3082:80: E501 line too long (82 > 79 characters)
Line 3203:1: W293 blank line contains whitespace
Line 3206:80: E501 line too long (92 > 79 characters)
Line 4734:80: E501 line too long (81 > 79 characters)

Comment last updated at 2024-03-25 17:59:45 UTC

[github-actions]

Linter Bot Results:

Hi @ljwoods2! Thanks for making this PR. We linted your code and found the following:

Some issues were found with the formatting of your code.

Code Location	Outcome
main package	⚠️ Possible failure
testsuite	✅ Passed

Please have a look at the darker-main-code and darker-test-code steps here for more details: https://github.com/MDAnalysis/mdanalysis/actions/runs/8424742406/job/23069336974

---

Please note: The black linter is purely informational, you can safely ignore these outcomes if there are no flake8 failures!

[IAlibay]

@ljwoods2 - could we ask you to revert the black auto formatting please? This not only makes reviews difficult but it also obscures the great work you're doing towards fixing this issue.

Auto formatting the library is an ongoing discussion, if it happens, it will be handled in a future PR.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 93.63%. Comparing base (0582265) to head (958a149).

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #4374      +/-   ##
===========================================
- Coverage    93.65%   93.63%   -0.03%     
===========================================
  Files          168      180      +12     
  Lines        21215    22294    +1079     
  Branches      3908     3908              
===========================================
+ Hits         19869    20875    +1006     
- Misses         888      961      +73     
  Partials       458      458              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[ljwoods2]

@IAlibay Done, I reverted a few things line-wise so I may have undone some PEP8 changes as well. In the future, should I change all the files I touch to be PEP-8 compliant, but not Black? Or do I only make the new code that I contribute PEP-8?

[RMeli]

In the future, should I change all the files I touch to be PEP-8 compliant, but not Black? Or do I only make the new code that I contribute PEP-8?

The second one. New code should be PEP-8 compliant, but you should not fix other issues in the same file (will make review murkier). I know it's not great if you have linters on on your editor/IDE because of the large amount of errors you see, but until we decide to reformat the whole code base, this remains the best way forward for the project. If you feel strongly about this, please add your view/experience in #2450.

[RMeli]

Cycling the PR to restart Codecov action.

n/a

[orbeckst]

This all looks nice to me and seems to work for me locally (make doctest).

However, I haven't been super-involved with doctesting so I wanted to know from @hmacdope @richardjgowers @IAlibay (people involved in #3925 — other opinions welcome, too, of course!) if using sphinx directives is ok? In other words, are we ok with the following not working:

pytest -v --disable-pytest-warnings --doctest-modules

and only

make doctest

aka

sphinx-build -v -W -b doctest --keep-going   source ../doctest

being used for doc-testing?

I'll block the PR until that's clear.

[orbeckst]

FYI, this is what the passing doctests look like

Document: documentation_pages/core/groups
-----------------------------------------
~/mdanalysis/package/MDAnalysis/topology/PDBParser.py:331: UserWarning: Element information is missing, elements attribute will not be populated. If needed these can be guessed using MDAnalysis.topology.guessers.
  warnings.warn("Element information is missing, elements attribute "
~/mdanalysis/package/MDAnalysis/core/selection.py:735: UserWarning: Your smarts-based atom selection returned the maxnumber of matches. This indicates that not allmatching atoms were selected. When callingatom_group.select_atoms(), the default valueof maxMatches is max(100, len(atom_group * 10)). To fix this, add the following argument to select_atoms: 
smarts_kwargs={maxMatches: <higher_value>}
  warnings.warn("Your smarts-based atom selection returned the max"
19 items passed all tests:
  16 tests in AtomGroup
  11 tests in AtomGroup.asunique
   7 tests in AtomGroup.select_atoms
   1 tests in AtomGroup.select_atoms.namedarguments
   1 tests in AtomGroup.select_atoms.smarts
   1 tests in AtomGroup.select_atoms.updating
  10 tests in AtomGroup.sort
  10 tests in AtomGroup.unique
  30 tests in GroupBase.center
  15 tests in GroupBase.concatenate
  12 tests in GroupBase.groupby
  18 tests in GroupBase.isunique
  12 tests in GroupBase.subtract
  12 tests in GroupBase.symmetric_difference
  12 tests in GroupBase.union
   7 tests in ResidueGroup.asunique
   7 tests in ResidueGroup.unique
   7 tests in SegmentGroup.asunique
   7 tests in SegmentGroup.unique
196 tests in 19 items.
196 passed and 0 failed.
Test passed.

[orbeckst]

Based on the comments on using sphinx in doc tests from discord, using sphinx is ok so I am approving.