Removing material for modules moved to MDAKits?

[fiona-naughton]

Ahead of MDAnalysis 3.0, several analysis modules are being deprecated in favour of MDAKit versions of themselves (e.g. psa, hole2, encore).

Most of these have been deprecated in the code (pending v2.8), but nothing changed yet in the User Guide. This should be updated, but there are a couple of options here:

1. Remove all references to these modules by 3.0. (Add deprecation warnings now and port all examples to their respective MDAKits' documentation; refer users generally to the MDAKit registry for additional tools, but don't mention anything specifically)
2. Leave the examples in the User Guide beyond 3.0. (Update the code snippets to correctly use the MDAKits; either duplicate to or link from respective MDAKits' documentation; refer users to MDAKits for other additional tools).
3. As 1, but include explicit mention of the MDAnalysis-owned MDAKits with e.g. a brief description and links.

Arguments for 1 are that it more cleanly follows the initial MDAKits idea of separating the core library and the "extra" code, i.e. there's less pressure on us to keep it up-to-date, material for those Kits can be updated independently etc. Also, having the examples on (only) the MDAKit side means we have better docs for other MDAKits to emulate, without worrying about duplicating stuff or keeping track of links like 2 [or 3] would require. In this option the User Guide is "core library only".

Arguments for 2 are that these MDAKits are still MDAnalysis-owned, and that the examples could still be useful for people generally wanting to play around with MDAnalysis and see e.g. plotting examples. It's also likely more work to port things to each MDAKit vs. just renaming modules in the UG, but not insurmountable. In this option the User Guide is generally for MDA-owned things.

Option 3 is a possible middle-ground, but potentially more trouble than it's worth.

We've started discussing this amongst the MDAKits team, but since it might involve moving a chunk out of the User Guide, if any @MDAnalysis/coredevs has any thoughts/opinions please do chime in.

[orbeckst]

I want to say that my original opinion was mostly along (2). However, reading through your summary, I gravitate to (3) as it is more in the spirit of MDAKits, reduces maintenance burden on the UG, but maintains the UG as an entry point for users.

[RMeli]

I'd vote for 3 too. The old versions of the User Guide are still available; if we ensure that 2.x is reachable, then it is fine to nuke all the irrelevant pages for 3.x. However, I think it is useful for users of 2.x transitioning to 3.x to have some information about the MDA-owned MDAKit and where to find them.