Merge pull request #1452 from cuthbertLab/doc-strike

Strike through deprecated in docs

documentation/docbuild/documenters.py

@@ -80,7 +80,7 @@ def makeRubric(text):
 
 class ObjectDocumenter(Documenter):
     '''
-    Base class for object documenting sub-classes. such as ClassDocumenter
+    Base class for object documenting subclasses. such as ClassDocumenter
     '''
 
     _DOC_ATTR: dict[str, str] = {
@@ -195,15 +195,15 @@ class MemberDocumenter(ObjectDocumenter):
     '''
     _DOC_ATTR: dict[str, str] = {
         'memberName': 'the short name of the member, for instance "mode"',
-        'referent': '''the attribute or method itself, such as (no quotes)
-                       key.KeySignature.mode''',
-        'definingClass': '''the class the referent belongs to, such as (no quotes)
-                            key.KeySignature''',
+        'referent': '''the attribute or method itself, such as
+                       <function KeySignature.mode at ...>''',
+        'definingClass': '''the class the referent belongs to, such as
+                            <class 'music21.key.KeySignature'>''',
     }
 
     # INITIALIZER #
 
-    def __init__(self, referent, memberName, definingClass):
+    def __init__(self, referent, memberName: str, definingClass: type):
         if not isinstance(definingClass, type):
             raise Music21Exception(f'referent must be a class, not {referent}')
         super().__init__(referent)
@@ -271,7 +271,12 @@ class MethodDocumenter(MemberDocumenter):
     @property
     def rstAutodocDirectiveFormat(self):
         result = []
-        result.append(f'.. automethod:: {self.referentPackageSystemPath}')
+        indent = ''
+        if getattr(self.referent, '_isDeprecated', False):
+            indent = '    '
+            result.append('.. cssclass:: strike')
+            result.append('')
+        result.append(f'{indent}.. automethod:: {self.referentPackageSystemPath}')
         result.append('')
         return result
 
@@ -1453,7 +1458,8 @@ def rstPageReferenceFormat(self):
 
     @property
     def referenceName(self):
-        '''The short name of the module:
+        '''
+        The short name of the module:
 
         >>> from music21 import serial
         >>> module = serial

documentation/docbuild/make.py

@@ -91,6 +91,7 @@ def runBuild(self, runSphinx=True):
 
     def runSphinx(self):
         try:
+            # noinspection PyPackageRequirements
             import sphinx
         except ImportError:
             message = 'Sphinx is required to build documentation; '

documentation/source/_themes/m21/static/m21.css

@@ -27,6 +27,10 @@ body {
     padding: 0 0 0 0;
 }
 
+.strike {
+  text-decoration: line-through;
+}
+
 pre, div[class*="highlight-"] {
     clear: left;
 }

music21/articulations.py

@@ -111,8 +111,8 @@ class Articulation(base.Music21Object):
     '''
     _styleClass: type[style.Style] = style.TextStyle
 
-    def __init__(self):
-        super().__init__()
+    def __init__(self, **keywords):
+        super().__init__(**keywords)
         self.placement = None
         # declare a unit interval shift for the performance of this articulation
         self._volumeShift: float = 0.0
@@ -214,8 +214,8 @@ class LengthArticulation(Articulation):
     '''
     Superclass for all articulations that change the length of a note.
     '''
-    def __init__(self):
-        super().__init__()
+    def __init__(self, **keywords):
+        super().__init__(**keywords)
         self.tieAttach = 'last'
 
 class DynamicArticulation(Articulation):
@@ -240,8 +240,8 @@ class Accent(DynamicArticulation):
 
     >>> a = articulations.Accent()
     '''
-    def __init__(self):
-        super().__init__()
+    def __init__(self, **keywords):
+        super().__init__(**keywords)
         self._volumeShift = 0.1
 
 
@@ -257,8 +257,8 @@ class StrongAccent(Accent):
     >>> a.pointDirection
     'down'
     '''
-    def __init__(self):
-        super().__init__()
+    def __init__(self, **keywords):
+        super().__init__(**keywords)
         self._volumeShift = 0.15
         self.pointDirection = 'up'
 
@@ -267,8 +267,8 @@ class Staccato(LengthArticulation):
 
     >>> a = articulations.Staccato()
     '''
-    def __init__(self):
-        super().__init__()
+    def __init__(self, **keywords):
+        super().__init__(**keywords)
         self._volumeShift = 0.05
         self.lengthShift = 0.7
 
@@ -279,8 +279,8 @@ class Staccatissimo(Staccato):
 
     >>> a = articulations.Staccatissimo()
     '''
-    def __init__(self):
-        super().__init__()
+    def __init__(self, **keywords):
+        super().__init__(**keywords)
         self._volumeShift = 0.05
         self.lengthShift = 0.5
 
@@ -296,7 +296,7 @@ class Spiccato(Staccato, Accent):
     >>> spiccato.volumeShift == accent.volumeShift
     True
     '''
-    def __init__(self):
+    def __init__(self, **keywords):
         Staccato.__init__(self)
         with tempAttribute(self, 'lengthShift'):
             Accent.__init__(self)  # order matters...
@@ -306,17 +306,17 @@ class Tenuto(LengthArticulation):
     '''
     >>> a = articulations.Tenuto()
     '''
-    def __init__(self):
-        super().__init__()
+    def __init__(self, **keywords):
+        super().__init__(**keywords)
         self._volumeShift = -0.05  # is this the right thing to do?
         self.lengthShift = 1.1
 
 class DetachedLegato(LengthArticulation):
     '''
     >>> a = articulations.DetachedLegato()
     '''
-    def __init__(self):
-        super().__init__()
+    def __init__(self, **keywords):
+        super().__init__(**keywords)
         self.lengthShift = 0.9
 
 # --------- indeterminate slides
@@ -353,8 +353,8 @@ class Doit(IndeterminateSlide):
 
     >>> a = articulations.Doit()
     '''
-    def __init__(self):
-        super().__init__()
+    def __init__(self, **keywords):
+        super().__init__(**keywords)
         self.tieAttach = 'last'
 
 class Falloff(IndeterminateSlide):
@@ -363,8 +363,8 @@ class Falloff(IndeterminateSlide):
 
     >>> a = articulations.Falloff()
     '''
-    def __init__(self):
-        super().__init__()
+    def __init__(self, **keywords):
+        super().__init__(**keywords)
         self.tieAttach = 'last'
 
 # --------- end indeterminate slide
@@ -377,8 +377,8 @@ class BreathMark(LengthArticulation):
     >>> a = articulations.BreathMark()
     >>> a.symbol = 'comma'
     '''
-    def __init__(self):
-        super().__init__()
+    def __init__(self, **keywords):
+        super().__init__(**keywords)
         self.lengthShift = 0.7
         self.symbol = None
 
@@ -393,8 +393,8 @@ class Stress(DynamicArticulation, LengthArticulation):
 
     >>> a = articulations.Stress()
     '''
-    def __init__(self):
-        super().__init__()
+    def __init__(self, **keywords):
+        super().__init__(**keywords)
         self._volumeShift = 0.05
         self.lengthShift = 1.1
 
@@ -404,8 +404,8 @@ class Unstress(DynamicArticulation):
 
     >>> a = articulations.Unstress()
     '''
-    def __init__(self):
-        super().__init__()
+    def __init__(self, **keywords):
+        super().__init__(**keywords)
         self._volumeShift = -0.05
 
 
@@ -461,8 +461,8 @@ class Fingering(TechnicalIndication):
     are mapped implicitly to the notes of a chord in order. Superfluous
     Fingerings will be ignored and may be discarded when serializing.
     '''
-    def __init__(self, fingerNumber=None):
-        super().__init__()
+    def __init__(self, fingerNumber=None, **keywords):
+        super().__init__(**keywords)
         self.fingerNumber = fingerNumber
         self.substitution = False
         self.alternate = False
@@ -496,8 +496,8 @@ class StringHarmonic(Bowing, Harmonic):
 
     >>> h.pitchType = 'base'
     '''
-    def __init__(self):
-        super().__init__()
+    def __init__(self, **keywords):
+        super().__init__(**keywords)
         self.harmonicType = 'natural'
         self.pitchType = None
 
@@ -518,8 +518,8 @@ class StringIndication(Bowing):
 
     If no argument to the constructor is specified, number defaults to 0.
     '''
-    def __init__(self, number=0):
-        super().__init__()
+    def __init__(self, number=0, **keywords):
+        super().__init__(**keywords)
         self.number = number
 
     def _reprInternal(self):
@@ -570,8 +570,8 @@ class FretIndication(TechnicalIndication):
 
     If no argument to the constructor is specified, number defaults to 0.
     '''
-    def __init__(self, number=0):
-        super().__init__()
+    def __init__(self, number=0, **keywords):
+        super().__init__(**keywords)
         self.number = number
 
     def _reprInternal(self):
@@ -629,8 +629,8 @@ class OrganIndication(TechnicalIndication):
     Has one attribute, "substitution" default to False, which
     indicates whether the mark is a substitution mark
     '''
-    def __init__(self):
-        super().__init__()
+    def __init__(self, **keywords):
+        super().__init__(**keywords)
         self.substitution = False