Always transplant a stub for transplanted methods

[jbarnoud]

Fixes #1845

Methods and properties defined by topology attributes and transplanted in various core classes (groups and Universe) do not appear in the documentation. Several solutions have been proposed to solve this problem:

• inspecting the code when generating the doc to programmatically add these methods to the doc: Generate doc tables for transplanted methods, continued #2418, [WIP] Generate doc stubs for transplanted methods #2176.
• move the transplanted method back in the core classes: Move transplanted methods into the core classes #2424.

Here, instead, I systematically transplant a dummy method in the core class for each method that is to be transplanted. The dummy method mimics the name, signature, and documentation of the original method, but always raises a NoDataError. The dummy methods (stubs) are picked up by sphinx and appear in the documentation. Also, the transplant methods from topology attributes that are not present in a given universe do not raise a confusing AttributeError any more, instead, they raise a NoDataError that specify which attribute is missing.

Compared to #2418, this method does not produce the cool looking tables and does not automatically tell that an attribute is required in the doc. It also has the same issue with reference duplicates (see #2176 (comment)). However, it does not require any manual operation.

The problem with the references is about one citation only, though.

Compared to #2424, it keeps all the benefit of the transplant as described in #601.

PR Checklist

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

[jbarnoud]

I will move the transplant of the stub in the metaclass to keep all the logic together.

[codecov]

Codecov Report

Merging #2427 into develop will decrease coverage by 0.00%.
The diff coverage is 95.12%.

@@             Coverage Diff             @@
##           develop    #2427      +/-   ##
===========================================
- Coverage    93.05%   93.05%   -0.01%     
===========================================
  Files          186      186              
  Lines        24611    24651      +40     
  Branches      3188     3194       +6     
===========================================
+ Hits         22902    22938      +36     
- Misses        1661     1665       +4     
  Partials        48       48              

Impacted Files	Coverage Δ
package/MDAnalysis/core/topologyattrs.py	96.44% <95.00%> (-0.06%)	⬇️
package/MDAnalysis/core/groups.py	98.58% <100.00%> (ø)
package/MDAnalysis/transformations/translate.py	95.23% <0.00%> (-4.77%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update beb5232...16dcb2d. Read the comment docs.

[pep8speaks]

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

• In the file package/setup.py:

Line 612:80: E501 line too long (81 > 79 characters)

Comment last updated at 2020-10-20 08:27:05 UTC

[jbarnoud]

This is what it looks like:

[jbarnoud]

I think this is ready for review. Maybe @lilyminium would have opinions about it.

[lilyminium]

This looks great, thank you @jbarnoud! However, if it's not too much work to bring the Python 2 funcsigs back in, it would be great to backport this PR to master so the transplanted methods are documented in the 1.0.x docs too -- the methods do exist in that version as well.

[jbarnoud]

@lilyminium I added back funcsign and got rid of an f-string to help with backport. The patch should work on python 2.7, but I did not try as the rest of develop doesn't. The uncovered code is the import of funcsign as it would only run on python 2.

[lilyminium]

Thank you @jbarnoud for this nice solution!

[orbeckst]

Thank you @jbarnoud – makes me happy that this is working.

We can remove the funcsig stuff again – but it makes it easier to backport because we can cherry pick.