From 540a9800e626e7a782424e938c07ba1ab06ce3ef Mon Sep 17 00:00:00 2001
From: Hugo MacDermott-Opeskin <hugomacdermott@gmail.com>
Date: Sun, 5 Nov 2023 20:24:37 +1100
Subject: [PATCH] Add DepWarnings to X3DNA code and docs (#4333)

* Deprecate x3dna, scheduled for removal in version 3.0
---
 package/CHANGELOG                           |  3 ++-
 package/MDAnalysis/analysis/legacy/x3dna.py | 24 +++++++++++++++++++--
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/package/CHANGELOG b/package/CHANGELOG
index 27456adf64d..0a0e42750f9 100644
--- a/package/CHANGELOG
+++ b/package/CHANGELOG
@@ -15,7 +15,7 @@ The rules for this file:
 
 -------------------------------------------------------------------------------
 ??/??/?? IAlibay, ianmkenney, PicoCentauri, pgbarletta, p-j-smith, 
-         richardjgowers, lilyminium, ALescoulie
+         richardjgowers, lilyminium, ALescoulie, hmacdope
 
  * 2.7.0
 
@@ -55,6 +55,7 @@ Changes
     `analysis.nucleicacids.WatsonCrickDist.results.distances` (Issue #3720, PR #3735)
 
 Deprecations
+  * X3DNA has been deprecated and will be removed in 3.0.0 (Issue #3788)
   * coordinates.base.ConverterBase has been deprecated and will be removed in 3.0.0;
     use converters.base.ConvertBase instead (Issue #3404)
   * In `nucleicacids.WatsonCrickDist`, accepting lists of `Residue` objects was deprecated
diff --git a/package/MDAnalysis/analysis/legacy/x3dna.py b/package/MDAnalysis/analysis/legacy/x3dna.py
index f27301cc5fe..9dc69a46702 100644
--- a/package/MDAnalysis/analysis/legacy/x3dna.py
+++ b/package/MDAnalysis/analysis/legacy/x3dna.py
@@ -132,13 +132,16 @@
 import matplotlib.pyplot as plt
 
 from MDAnalysis import ApplicationError
-from MDAnalysis.lib.util import which, realpath, asiterable
+from MDAnalysis.lib.util import which, realpath, asiterable, deprecate
 
 import logging
 
 logger = logging.getLogger("MDAnalysis.analysis.x3dna")
 
 
+@deprecate(release="2.7.0", remove="3.0.0",
+           message=("X3DNA module is deprecated and will be removed in" 
+                    "MDAnalysis 3.0.0, see #3788"))
 def mean_std_from_x3dnaPickle(profile):
     """Get mean and standard deviation of helicoidal parameters from a saved `profile`.
 
@@ -162,7 +165,10 @@ def mean_std_from_x3dnaPickle(profile):
         stretch, stagger, buckle, propeller, opening, shift, slide, rise, tilt,
         roll, twist]``.
 
+    .. deprecated:: 2.7.0
+        X3DNA will be removed in 3.0.0.
     """
+    warnings.warn("X3DNA module is deprecated and will be removed in MDAnalysis 3.0, see #3788", category=DeprecationWarning)
     if profile.x3dna_param is False:
         bp_shear, bp_stretch, bp_stagger, bp_rise, bp_shift, bp_slide, bp_buckle, bp_prop, bp_open, bp_tilt, bp_roll,\
             bp_twist = [], [], [], [], [], [], [], [], [], [], [], []
@@ -247,6 +253,9 @@ class BaseX3DNA(object):
 
     for each nucleic acid pair.
 
+    .. deprecated:: 2.7.0
+        X3DNA will be removed in 3.0.0.
+
     .. _X3DNA: http://x3dna.org
 
     """
@@ -472,9 +481,15 @@ class X3DNA(BaseX3DNA):
 
     .. versionadded:: 0.8
 
+    .. deprecated:: 2.7.0
+        X3DNA will be removed in 3.0.0.
+
     .. _`X3DNA docs`: http://forum.x3dna.org/
     """
 
+    @deprecate(release="2.7.0", remove="3.0.0",
+           message=("X3DNA module is deprecated and will be removed in" 
+                    "MDAnalysis 3.0.0, see #3788"))
     def __init__(self, filename, **kwargs):
         """Set up parameters to run X3DNA_ on PDB *filename*.
 
@@ -717,8 +732,13 @@ class X3DNAtraj(BaseX3DNA):
     universe and feed it to X3DNA. By default it sequentially creates a PDB for
     each frame and runs X3DNA on the frame.
 
-    """
 
+    .. deprecated:: 2.7.0
+        X3DNA will be removed in 3.0.0.
+    """
+    @deprecate(release="2.7.0", remove="3.0.0",
+           message=("X3DNA module is deprecated and will be removed in" 
+                    "MDAnalysis 3.0.0, see #3788"))
     def __init__(self, universe, **kwargs):
         """Set up the class.