Change documentation from epydoc to reStructuredText

Thanks to Freso for all the useful comments!

Signed-off-by: JoeLametta <JoeLametta@users.noreply.github.com>

whipper/common/cache.py

@@ -39,7 +39,7 @@ class Persister:
     Call persist to store the object to disk; it will get stored if it
     changed from the on-disk object.
 
-    @ivar object: the persistent object
+    :ivar object: the persistent object
     """
 
     def __init__(self, path=None, default=None):
@@ -162,7 +162,7 @@ def getRipResult(self, cddbdiscid, create=True):
         Retrieve the persistable RipResult either from our cache (from a
         previous, possibly aborted rip), or return a new one.
 
-        @rtype: L{Persistable} for L{result.RipResult}
+        :rtype: :any:`Persistable` for :any:`result.RipResult`
         """
         presult = self._pcache.get(cddbdiscid)
 

whipper/common/common.py

@@ -56,11 +56,11 @@ def msfToFrames(msf):
     """
     Converts a string value in MM:SS:FF to frames.
 
-    @param msf: the MM:SS:FF value to convert
-    @type  msf: str
+    :param msf: the MM:SS:FF value to convert
+    :type  msf: str
 
-    @rtype:   int
-    @returns: number of frames
+    :rtype:   int
+    :returns: number of frames
     """
     if ':' not in msf:
         return int(msf)
@@ -104,14 +104,14 @@ def formatTime(seconds, fractional=3):
     If it is greater than 0, we will show seconds and fractions of seconds.
     As a side consequence, there is no way to show seconds without fractions.
 
-    @param seconds:    the time in seconds to format.
-    @type  seconds:    int or float
-    @param fractional: how many digits to show for the fractional part of
+    :param seconds:    the time in seconds to format.
+    :type  seconds:    int or float
+    :param fractional: how many digits to show for the fractional part of
                        seconds.
-    @type  fractional: int
+    :type  fractional: int
 
-    @rtype: string
-    @returns: a nicely formatted time string.
+    :rtype: string
+    :returns: a nicely formatted time string.
     """
     chunks = []
 
@@ -207,11 +207,11 @@ def getRealPath(refPath, filePath):
     Does Windows path translation.
     Will look for the given file name, but with .flac and .wav as extensions.
 
-    @param refPath:  path to the file from which the track is referenced;
+    :param refPath:  path to the file from which the track is referenced;
                      for example, path to the .cue file in the same directory
-    @type  refPath:  unicode
+    :type  refPath:  unicode
 
-    @type  filePath: unicode
+    :type  filePath: unicode
     """
     assert isinstance(filePath, unicode), "%r is not unicode" % filePath
 
@@ -300,11 +300,11 @@ class VersionGetter(object):
 
     def __init__(self, dependency, args, regexp, expander):
         """
-        @param dependency: name of the dependency providing the program
-        @param args:       the arguments to invoke to show the version
-        @type  args:       list of str
-        @param regexp:     the regular expression to get the version
-        @param expander:   the expansion string for the version using the
+        :param dependency: name of the dependency providing the program
+        :param args:       the arguments to invoke to show the version
+        :type  args:       list of str
+        :param regexp:     the regular expression to get the version
+        :param expander:   the expansion string for the version using the
                            regexp group dict
         """
 

whipper/common/mbngs.py

@@ -58,13 +58,13 @@ class TrackMetadata(object):
 
 class DiscMetadata(object):
     """
-    @param artist:       artist(s) name
-    @param sortName:     release artist sort name
-    @param release:      earliest release date, in YYYY-MM-DD
-    @type  release:      unicode
-    @param title:        title of the disc (with disambiguation)
-    @param releaseTitle: title of the release (without disambiguation)
-    @type  tracks:       C{list} of L{TrackMetadata}
+    :param artist:       artist(s) name
+    :param sortName:     release artist sort name
+    :param release:      earliest release date, in YYYY-MM-DD
+    :type  release:      unicode
+    :param title:        title of the disc (with disambiguation)
+    :param releaseTitle: title of the release (without disambiguation)
+    :type  tracks:       list of :any:`TrackMetadata`
     """
     artist = None
     sortName = None
@@ -163,11 +163,11 @@ def _getWorks(recording):
 
 def _getMetadata(release, discid, country=None):
     """
-    @type  release: C{dict}
-    @param release: a release dict as returned in the value for key release
+    :type  release: dict
+    :param release: a release dict as returned in the value for key release
                     from get_release_by_id
 
-    @rtype: L{DiscMetadata} or None
+    :rtype: DiscMetadata or None
     """
     logger.debug('getMetadata for release id %r', release['id'])
     if not release['id']:
@@ -281,9 +281,9 @@ def musicbrainz(discid, country=None, record=False):
 
     Example disc id: Mj48G109whzEmAbPBoGvd4KyCS4-
 
-    @type  discid: str
+    :type  discid: str
 
-    @rtype: list of L{DiscMetadata}
+    :rtype: list of :any:`DiscMetadata`
     """
     logger.debug('looking up results for discid %r', discid)
     import musicbrainzngs

whipper/common/path.py

@@ -28,10 +28,10 @@ class PathFilter(object):
 
     def __init__(self, slashes=True, quotes=True, fat=True, special=False):
         """
-        @param slashes: whether to convert slashes to dashes
-        @param quotes:  whether to normalize quotes
-        @param fat:     whether to strip characters illegal on FAT filesystems
-        @param special: whether to strip special characters
+        :param slashes: whether to convert slashes to dashes
+        :param quotes:  whether to normalize quotes
+        :param fat:     whether to strip characters illegal on FAT filesystems
+        :param special: whether to strip special characters
         """
         self._slashes = slashes
         self._quotes = quotes

whipper/common/program.py

@@ -44,12 +44,11 @@ class Program:
     """
     I maintain program state and functionality.
 
-    @ivar metadata:
-    @type metadata: L{mbngs.DiscMetadata}
-    @ivar result:   the rip's result
-    @type result:   L{result.RipResult}
-    @type outdir:   unicode
-    @type config:   L{whipper.common.config.Config}
+    :vartype metadata: mbngs.DiscMetadata
+    :cvar result:      the rip's result
+    :vartype result:   result.RipResult
+    :vartype outdir:   unicode
+    :vartype config:   whipper.common.config.Config
     """
 
     cuePath = None
@@ -60,7 +59,7 @@ class Program:
 
     def __init__(self, config, record=False):
         """
-        @param record: whether to record results of API calls for playback.
+        :param record: whether to record results of API calls for playback.
         """
         self._record = record
         self._cache = cache.ResultCache()
@@ -109,7 +108,7 @@ def getTable(self, runner, cddbdiscid, mbdiscid, device, offset,
         """
         Retrieve the Table either from the cache or the drive.
 
-        @rtype: L{table.Table}
+        :rtype: table.Table
         """
         tcache = cache.TableCache()
         ptable = tcache.get(cddbdiscid, mbdiscid)
@@ -153,7 +152,7 @@ def getRipResult(self, cddbdiscid):
         Retrieve the persistable RipResult either from our cache (from a
         previous, possibly aborted rip), or return a new one.
 
-        @rtype: L{result.RipResult}
+        :rtype: result.RipResult
         """
         assert self.result is None
 
@@ -247,9 +246,9 @@ def getPath(self, outdir, template, mbdiscid, metadata, track_number=None):
     @staticmethod
     def getCDDB(cddbdiscid):
         """
-        @param cddbdiscid: list of id, tracks, offsets, seconds
+        :param cddbdiscid: list of id, tracks, offsets, seconds
 
-        @rtype: str
+        :rtype: str
         """
         # FIXME: convert to nonblocking?
         try:
@@ -272,7 +271,7 @@ def getCDDB(cddbdiscid):
     def getMusicBrainz(self, ittoc, mbdiscid, release=None, country=None,
                        prompt=False):
         """
-        @type  ittoc: L{whipper.image.table.Table}
+        :type  ittoc: whipper.image.table.Table
         """
         # look up disc on MusicBrainz
         print('Disc duration: %s, %d audio tracks' % (
@@ -392,10 +391,10 @@ def getTagList(self, number, mbdiscid):
         """
         Based on the metadata, get a dict of tags for the given track.
 
-        @param number:   track number (0 for HTOA)
-        @type  number:   int
+        :param number:   track number (0 for HTOA)
+        :type  number:   int
 
-        @rtype: dict
+        :rtype: dict
         """
         trackArtist = u'Unknown Artist'
         releaseArtist = u'Unknown Artist'
@@ -461,7 +460,7 @@ def getHTOA(self):
         """
         Check if we have hidden track one audio.
 
-        @returns: tuple of (start, stop), or None
+        :returns: tuple of (start, stop), or None
         """
         track = self.result.table.tracks[0]
         try:
@@ -498,8 +497,8 @@ def ripTrack(self, runner, trackResult, offset, device, taglist,
         Ripping the track may change the track's filename as stored in
         trackResult.
 
-        @param trackResult: the object to store information in.
-        @type  trackResult: L{result.TrackResult}
+        :param trackResult: the object to store information in.
+        :type  trackResult: result.TrackResult
         """
         if trackResult.number == 0:
             start, stop = self.getHTOA()

whipper/common/renamer.py

@@ -109,10 +109,10 @@ def addRename(self, source, destination):
         """
         Add a rename operation.
 
-        @param source:      source filename
-        @type  source:      str
-        @param destination: destination filename
-        @type  destination: str
+        :param source:      source filename
+        :type  source:      str
+        :param destination: destination filename
+        :type  destination: str
         """
 
 
@@ -142,16 +142,16 @@ def redo(self):
     def serialize(self):
         """
         Serialize the operation.
-        The return value should bu usable with L{deserialize}
+        The return value should bu usable with :any:`deserialize`
 
-        @rtype: str
+        :rtype: str
         """
 
     def deserialize(cls, data):
         """
         Deserialize the operation with the given operation data.
 
-        @type  data: str
+        :type  data: str
         """
         raise NotImplementedError
     deserialize = classmethod(deserialize)

whipper/extern/task/task.py

@@ -97,8 +97,8 @@ class Task(LogStub):
     stopping myself from running.
     The listener can then handle the Task.exception.
 
-    @ivar  description: what am I doing
-    @ivar  exception:   set if an exception happened during the task
+    :cvar  description: what am I doing
+    :cvar  exception:   set if an exception happened during the task
                         execution.  Will be raised through run() at the end.
     """
     logCategory = 'Task'
@@ -254,16 +254,16 @@ def progressed(self, task, value):
         """
         Implement me to be informed about progress.
 
-        @type  value: float
-        @param value: progress, from 0.0 to 1.0
+        :type  value: float
+        :param value: progress, from 0.0 to 1.0
         """
 
     def described(self, task, description):
         """
         Implement me to be informed about description changes.
 
-        @type  description: str
-        @param description: description
+        :type  description: str
+        :param description: description
         """
 
     def started(self, task):
@@ -298,8 +298,8 @@ class BaseMultiTask(Task, ITaskListener):
     """
     I perform multiple tasks.
 
-    @ivar tasks: the tasks to run
-    @type tasks: list of L{Task}
+    :ivar tasks: the tasks to run
+    :type tasks: list of :any:`Task`
     """
 
     description = 'Doing various tasks'
@@ -313,7 +313,7 @@ def addTask(self, task):
         """
         Add a task.
 
-        @type task: L{Task}
+        :type task: Task
         """
         if self.tasks is None:
             self.tasks = []
@@ -446,7 +446,7 @@ def run(self, task):
         """
         Run the given task.
 
-        @type  task: Task
+        :type  task: Task
         """
         raise NotImplementedError
 
@@ -457,8 +457,8 @@ def schedule(self, delta, callable_task, *args, **kwargs):
 
         Subclasses should implement this.
 
-        @type  delta: float
-        @param delta: time in the future to schedule call for, in seconds.
+        :type  delta: float
+        :param delta: time in the future to schedule call for, in seconds.
         """
         raise NotImplementedError