convert most documentation markup

dak/check_archive.py

@@ -83,7 +83,7 @@ The following MODEs are available:
 def process_dir(unused, dirname: str, filenames: dict) -> None:
     """
     Process a directory and output every files name which is not listed already
-    in the C{filenames} or global C{excluded} dictionaries.
+    in the `filenames` or global :data:`excluded` dictionaries.
 
     :param dirname: the directory to look at
     :param filenames: Known filenames to ignore

dak/dakdb/__init__.py

 """
-Database update scripts for usage with B{dak update-db}
+Database update scripts for usage with ``dak update-db``
 
 @contact: Debian FTP Master <ftpmaster@debian.org>
 @copyright: 2008  Michael Casadevall <mcasadevall@debian.org>
 @license: GNU General Public License version 2 or later
 
-Update scripts have to C{import psycopg2} and
-C{from daklib.dak_exceptions import DBUpdateError}.
+Update scripts have to ``import psycopg2`` and
+``from daklib.dak_exceptions import DBUpdateError``.
 
-There has to be B{at least} the function C{do_update(self)} to be
+There has to be **at least** the function ``do_update(self)`` to be
 defined. It should take all neccessary steps to update the
 database. If the update fails the changes have to be rolled back and the
-C{DBUpdateError} exception raised to properly halt the execution of any
-other update.
+:exc:`~daklib.dak_exceptions.DBUpdateError` exception raised to properly
+halt the execution of any other update.
 
 Example::
+
  def do_update(self):
-     print "Doing something"
+     print("Doing something")
 
      try:
          c = self.db.cursor()
          c.execute("SOME SQL STATEMENT")
          self.db.commit()
 
-     except psycopg2.ProgrammingError, msg:
+     except psycopg2.ProgrammingError as msg:
          self.db.rollback()
-         raise DBUpdateError("Unable to do whatever, rollback issued. Error message : %s" % (str(msg)))
+         raise DBUpdateError(f"Unable to do whatever, rollback issued. Error message: {msg}")
 
 This function can do whatever it wants and use everything from dak and
 daklib.

dak/process_new.py

@@ -451,7 +451,7 @@ def run_user_inspect_command(upload: daklib.dbconn.PolicyQueueUpload, upload_cop
 def get_reject_reason(reason: str = '') -> Optional[str]:
     """get reason for rejection
 
-    :return: string giving the reason for the rejection or C{None} if the
+    :return: string giving the reason for the rejection or :const:`None` if the
              rejection should be cancelled
     """
     answer = 'E'
@@ -650,7 +650,7 @@ ENVIRONMENT VARIABLES
 @contextlib.contextmanager
 def lock_package(package: str):
     """
-    Lock C{package} so that noone else jumps in processing it.
+    Lock `package` so that noone else jumps in processing it.
 
     :param package: source package name to lock
     """

dak/transitions.py

@@ -60,7 +60,9 @@ def init():
     """
     Initialize. Sets up database connection, parses commandline arguments.
 
-    @attention: This function may run B{within sudo}
+    .. warning::
+
+       This function may run **within sudo**
 
     """
     global Cnf, Options
@@ -129,11 +131,11 @@ def load_transitions(trans_file: str) -> Optional[dict]:
 
     .. warning::
 
-       This function may run B{within sudo}
+       This function may run **within sudo**
 
     :param trans_file: filename to parse
     :return: validated dictionary of transition entries or None
-             if validation fails, empty string if reading C{trans_file}
+             if validation fails, empty string if reading `trans_file`
              returned something else than a dict
 
     """
@@ -228,7 +230,7 @@ def lock_file(f):
 
     .. warning::
 
-       This function may run B{within sudo}
+       This function may run **within sudo**
     """
     for retry in range(10):
         lock_fd = os.open(f, os.O_RDWR | os.O_CREAT)
@@ -262,9 +264,9 @@ def write_transitions(from_trans: dict) -> None:
 
     .. warning::
 
-       This function may run B{within sudo}
+       This function may run **within sudo**
 
-    :param from_trans: transitions dictionary, as returned by L{load_transitions}
+    :param from_trans: transitions dictionary, as returned by :func:`load_transitions`
     """
 
     trans_file = Cnf["Dinstall::ReleaseTransitions"]
@@ -294,7 +296,7 @@ def write_transitions_from_file(from_file: str) -> None:
 
     .. warning::
 
-       This function usually runs B{within sudo}
+       This function usually runs **within sudo**
 
     :param from_file: filename of a transitions file
     """
@@ -523,7 +525,7 @@ Blocked Packages (total: %d): %s
 def transition_info(transitions: dict):
     """
     Print information about all defined transitions.
-    Calls L{get_info} for every transition and then tells user if the transition is
+    Calls :func:`get_info` for every transition and then tells user if the transition is
     still ongoing or if the expected version already hit testing.
 
     :param transitions: defined transitions
@@ -563,8 +565,9 @@ def main():
     """
     Prepare the work to be done, do basic checks.
 
-    @attention: This function may run B{within sudo}
+    .. warning::
 
+       This function may run **within sudo**
     """
     global Cnf
 

daklib/announce.py

@@ -58,7 +58,7 @@ def _subst_for_upload(upload: ProcessedUpload) -> dict:
     """ Prepare substitutions used for announce mails.
 
     :param upload: upload to handle
-    :return: A dict of substition values for use by L{daklib.utils.TemplateSubst}
+    :return: A dict of substition values for use by :func:`daklib.utils.TemplateSubst`
     """
     cnf = Config()
 

daklib/archive.py

@@ -58,7 +58,7 @@ class ArchiveTransaction:
         self.session = DBConn().session()
 
     def get_file(self, hashed_file: daklib.upload.HashedFile, source_name: str, check_hashes: bool = True) -> PoolFile:
-        """Look for file C{hashed_file} in database
+        """Look for file `hashed_file` in database
 
         :param hashed_file: file to look for in the database
         :param source_name: source package name
@@ -122,9 +122,9 @@ class ArchiveTransaction:
         :param allow_tainted: allow to copy additional files from tainted archives
         :param fingerprint: optional fingerprint
         :param source_suites: suites to copy the source from if they are not
-                              in C{suite} or C{True} to allow copying from any
+                              in `suite` or :const:`True` to allow copying from any
                               suite.
-                              Can be a SQLAlchemy subquery for C{daklib.dbconn.Suite} or C{True}.
+                              Can be a SQLAlchemy subquery for :class:`Suite` or :const:`True`.
         :param extra_source_archives: extra archives to copy Built-Using sources from
         :return: database object for the new package
         """
@@ -198,7 +198,7 @@ class ArchiveTransaction:
         :param source: source to look for
         :param archive: archive to look in
         :param extra_archives: list of archives to copy the source package from
-                               if it is not yet present in C{archive}
+                               if it is not yet present in `archive`
         """
         session = self.session
         db_file = session.query(ArchiveFile).filter_by(file=source.poolfile, archive=archive).first()
@@ -219,7 +219,7 @@ class ArchiveTransaction:
             self._copy_file(af.file, archive, db_file.component, allow_tainted=True)
 
     def _add_built_using(self, db_binary, filename, control, suite, extra_archives=None) -> None:
-        """Add Built-Using sources to C{db_binary.extra_sources}
+        """Add Built-Using sources to ``db_binary.extra_sources``
         """
         session = self.session
 
@@ -490,7 +490,7 @@ def source_component_from_package_list(package_list: 'daklib.packagelist.Package
 
     :param package_list: package list of the source to get the override for
     :param suite: suite to consider for binaries produced
-    :return: component for the given source or C{None}
+    :return: component for the given source or :const:`None`
     """
     if package_list.fallback:
         return None
@@ -528,7 +528,7 @@ class ArchiveUpload:
         """upload to process"""
 
         self.directory: str = None
-        """directory with temporary copy of files. set by C{prepare}"""
+        """directory with temporary copy of files. set by :meth:`prepare`"""
 
         self.keyrings = keyrings
 
@@ -549,10 +549,10 @@ class ArchiveUpload:
         self.final_suites = None
 
         self.new: bool = False
-        """upload is NEW. set by C{check}"""
+        """upload is NEW. set by :meth:`check`"""
 
         self._checked: bool = False
-        """checks passes. set by C{check}"""
+        """checks passes. set by :meth:`check`"""
 
         self._new_queue = self.session.query(PolicyQueue).filter_by(queue_name='new').one()
         self._new = self._new_queue.suite
@@ -560,7 +560,7 @@ class ArchiveUpload:
     def warn(self, message: str) -> None:
         """add a warning message
 
-        Adds a warning message that can later be seen in C{self.warnings}
+        Adds a warning message that can later be seen in :attr:`warnings`
 
         :param message: warning message
         """
@@ -571,7 +571,7 @@ class ArchiveUpload:
 
         This copies the files involved to a temporary directory.  If you use
         this method directly, you have to remove the directory given by the
-        C{directory} attribute later on your own.
+        :attr:`directory` attribute later on your own.
 
         Instead of using the method directly, you can also use a with-statement::
 
@@ -636,11 +636,11 @@ class ArchiveUpload:
         """Path to unpacked source
 
         Get path to the unpacked source. This method does unpack the source
-        into a temporary directory under C{self.directory} if it has not
+        into a temporary directory under :attr:`directory` if it has not
         been done so already.
 
         :return: string giving the path to the unpacked source directory
-                 or C{None} if no source was included in the upload.
+                 or :const:`None` if no source was included in the upload.
         """
         assert self.directory is not None
 
@@ -734,13 +734,13 @@ class ArchiveUpload:
         """Check if upload is NEW
 
         An upload is NEW if it has binary or source packages that do not have
-        an override in C{overridesuite} OR if it references files ONLY in a
+        an override in `overridesuite` OR if it references files ONLY in a
         tainted archive (eg. when it references files in NEW).
 
         Debug packages (*-dbgsym in Section: debug) are not considered as NEW
-        if C{suite} has a separate debug suite.
+        if `suite` has a separate debug suite.
 
-        :return: C{True} if the upload is NEW, C{False} otherwise
+        :return: :const:`True` if the upload is NEW, :const:`False` otherwise
         """
         session = self.session
         new = False
@@ -793,7 +793,7 @@ class ArchiveUpload:
 
         :param suite: suite to get override for
         :param binary: binary to get override for
-        :return: override for the given binary or C{None}
+        :return: override for the given binary or :const:`None`
         """
         if suite.overridesuite is not None:
             suite = self.session.query(Suite).filter_by(suite_name=suite.overridesuite).one()
@@ -813,7 +813,7 @@ class ArchiveUpload:
 
         :param suite: suite to get override for
         :param source: source to get override for
-        :return: override for the given source or C{None}
+        :return: override for the given source or :const:`None`
         """
         if suite.overridesuite is not None:
             suite = self.session.query(Suite).filter_by(suite_name=suite.overridesuite).one()
@@ -831,7 +831,7 @@ class ArchiveUpload:
         """get component for a binary
 
         By default this will only look at overrides to get the right component;
-        if C{only_overrides} is C{False} this method will also look at the
+        if `only_overrides` is :const:`False` this method will also look at the
         Section field.
 
         :param only_overrides: only use overrides to get the right component
@@ -847,7 +847,7 @@ class ArchiveUpload:
         """get component for a source
 
         By default this will only look at overrides to get the right component;
-        if C{only_overrides} is C{False} this method will also look at the
+        if `only_overrides` is :const:`False` this method will also look at the
         Section field.
 
         :param only_overrides: only use overrides to get the right component
@@ -863,7 +863,7 @@ class ArchiveUpload:
         """run checks against the upload
 
         :param force: ignore failing forcable checks
-        :return: C{True} if all checks passed, C{False} otherwise
+        :return: :const:`True` if all checks passed, :const:`False` otherwise
         """
         # XXX: needs to be better structured.
         assert self.changes.valid_signature
@@ -936,16 +936,16 @@ class ArchiveUpload:
         :param target_suite: target suite (before redirection to policy queue or NEW)
         :param suite: suite to install the package into. This is the real suite,
                       ie. after any redirection to NEW or a policy queue
-        :param source_component_func: function to get the L{daklib.dbconn.Component}
-                                      for a L{daklib.upload.Source} object
-        :param binary_component_func: function to get the L{daklib.dbconn.Component}
-                                      for a L{daklib.upload.Binary} object
-        :param source_suites: see L{daklib.archive.ArchiveTransaction.install_binary}
-        :param extra_source_archives: see L{daklib.archive.ArchiveTransaction.install_binary}
+        :param source_component_func: function to get the :class:`daklib.dbconn.Component`
+                                      for a :class:`daklib.upload.Source` object
+        :param binary_component_func: function to get the :class:`daklib.dbconn.Component`
+                                      for a :class:`daklib.upload.Binary` object
+        :param source_suites: see :meth:`daklib.archive.ArchiveTransaction.install_binary`
+        :param extra_source_archives: see :meth:`daklib.archive.ArchiveTransaction.install_binary`
         :param policy_upload: Boolean indicating upload to policy queue (including NEW)
-        :return: tuple with two elements. The first is a L{daklib.dbconn.DBSource}
-                 object for the install source or C{None} if no source was
-                 included. The second is a list of L{daklib.dbconn.DBBinary}
+        :return: tuple with two elements. The first is a :class:`daklib.dbconn.DBSource`
+                 object for the install source or :const:`None` if no source was
+                 included. The second is a list of :class:`daklib.dbconn.DBBinary`
                  objects for the installed binary packages.
         """
         # XXX: move this function to ArchiveTransaction?
@@ -1177,10 +1177,10 @@ class ArchiveUpload:
     def install(self) -> None:
         """install upload
 
-        Install upload to a suite or policy queue.  This method does B{not}
+        Install upload to a suite or policy queue.  This method does **not**
         handle uploads to NEW.
 
-        You need to have called the C{check} method before calling this method.
+        You need to have called the :meth:`check` method before calling this method.
         """
         assert len(self.reject_reasons) == 0
         assert self.changes.valid_signature
@@ -1233,10 +1233,10 @@ class ArchiveUpload:
     def install_to_new(self) -> None:
         """install upload to NEW
 
-        Install upload to NEW.  This method does B{not} handle regular uploads
+        Install upload to NEW.  This method does **not** handle regular uploads
         to suites or policy queues.
 
-        You need to have called the C{check} method before calling this method.
+        You need to have called the :meth:`check` method before calling this method.
         """
         # Uploads to NEW are special as we don't have overrides.
         assert len(self.reject_reasons) == 0

daklib/checks.py

@@ -20,7 +20,7 @@
 
 """module provided pre-acceptance tests
 
-Please read the documentation for the L{Check} class for the interface.
+Please read the documentation for the :class:`Check` class for the interface.
 """
 
 from daklib.config import Config
@@ -89,8 +89,8 @@ class RejectACL(Reject):
 class Check:
     """base class for checks
 
-    checks are called by L{daklib.archive.ArchiveUpload}. Failing tests should
-    raise a L{daklib.checks.Reject} exception including a human-readable
+    checks are called by :class:`daklib.archive.ArchiveUpload`. Failing tests should
+    raise a :exc:`daklib.checks.Reject` exception including a human-readable
     description why the upload should be rejected.
     """
 
@@ -117,8 +117,8 @@ class Check:
     def forcable(self) -> bool:
         """allow to force ignore failing test
 
-        C{True} if it is acceptable to force ignoring a failing test,
-        C{False} otherwise
+        :const:`True` if it is acceptable to force ignoring a failing test,
+        :const:`False` otherwise
         """
         return False
 

daklib/command.py

@@ -137,8 +137,8 @@ class CommandFile:
     def evaluate(self) -> bool:
         """evaluate commands file
 
-        :return: C{True} if the file was processed sucessfully,
-                 C{False} otherwise
+        :return: :const:`True` if the file was processed sucessfully,
+                 :const:`False` otherwise
         """
         result = True
 

daklib/dbconn.py

@@ -281,7 +281,7 @@ __all__.append('Architecture')
 @session_wrapper
 def get_architecture(architecture: str, session=None) -> Optional[Architecture]:
     """
-    Returns database id for given C{architecture}.
+    Returns database id for given `architecture`.
 
     :param architecture: The name of the architecture
     :param session: Optional SQLA session object (a temporary one will be
@@ -312,7 +312,7 @@ __all__.append('Archive')
 @session_wrapper
 def get_archive(archive: str, session=None) -> Optional[Archive]:
     """
-    returns database id for given C{archive}.
+    returns database id for given `archive`.
 
     :param archive: the name of the arhive
     :param session: Optional SQLA session object (a temporary one will be
@@ -444,7 +444,7 @@ __all__.append('DBBinary')
 @session_wrapper
 def get_suites_binary_in(package: str, session=None) -> 'list[Suite]':
     """
-    Returns list of Suite objects which given C{package} name is in
+    Returns list of Suite objects which given `package` name is in
 
     :param package: DBBinary package name to search for
     :return: list of Suite objects for the given package
@@ -530,7 +530,7 @@ __all__.append('Component')
 @session_wrapper
 def get_component(component: str, session=None) -> Optional[Component]:
     """
-    Returns database id for given C{component}.
+    Returns database id for given `component`.
 
     :param component: The name of the override type
     :return: the database id for the given component
@@ -571,7 +571,7 @@ def get_mapped_component(component_name: str, session=None) -> Optional[Componen
 
     :param component_name: component name
     :param session: database session
-    :return: component after applying maps or C{None}
+    :return: component after applying maps or :const:`None`
     """
     component_name = get_mapped_component_name(component_name)
     component = session.query(Component).filter_by(component_name=component_name).first()
@@ -917,11 +917,11 @@ __all__.append('Keyring')
 @session_wrapper
 def get_keyring(keyring: str, session=None) -> Optional[Keyring]:
     """
-    If C{keyring} does not have an entry in the C{keyrings} table yet, return None
-    If C{keyring} already has an entry, simply return the existing Keyring
+    If `keyring` does not have an entry in the `keyrings` table yet, return None
+    If `keyring` already has an entry, simply return the existing :class:`Keyring`
 
     :param keyring: the keyring name
-    :return: the Keyring object for this keyring
+    :return: the :class:`Keyring` object for this keyring
     """
 
     q = session.query(Keyring).filter_by(keyring_name=keyring)
@@ -958,12 +958,12 @@ __all__.append('DBChange')
 @session_wrapper
 def get_dbchange(filename: str, session=None) -> Optional[DBChange]:
     """
-    returns DBChange object for given C{filename}.
+    returns DBChange object for given `filename`.
 
     :param filename: the name of the file
     :param session: Optional SQLA session object (a temporary one will be
        generated if not supplied)
-    :return:  DBChange object for the given filename (C{None} if not present)
+    :return:  DBChange object for the given filename (:const:`None` if not present)
     """
     q = session.query(DBChange).filter_by(changesname=filename)
     return q.one_or_none()
@@ -1025,11 +1025,11 @@ __all__.append('get_or_set_maintainer')
 @session_wrapper
 def get_maintainer(maintainer_id: int, session=None) -> Optional[Maintainer]:
     """
-    Return the name of the maintainer behind C{maintainer_id} or None if that
-    maintainer_id is invalid.
+    Return the name of the maintainer behind `maintainer_id` or :const:`None`
+    if that `maintainer_id` is invalid.
 
     :param maintainer_id: the id of the maintainer
-    :return: the Maintainer with this C{maintainer_id}
+    :return: the Maintainer with this `maintainer_id`
     """
 
     return session.query(Maintainer).get(maintainer_id)
@@ -1054,7 +1054,7 @@ __all__.append('NewComment')
 @session_wrapper
 def has_new_comment(policy_queue, package: str, version: str, session=None) -> bool:
     """
-    Returns true if the given combination of C{package}, C{version} has a comment.
+    Returns :const:`True` if the given combination of `package`, `version` has a comment.
 
     :param package: name of the package
     :param version: package version
@@ -1189,7 +1189,7 @@ __all__.append('OverrideType')
 @session_wrapper
 def get_override_type(override_type: str, session=None) -> Optional[OverrideType]:
     """
-    Returns OverrideType object for given C{override type}.
+    Returns OverrideType object for given `override_type`.
 
     :param override_type: The name of the override type
     :param session: Optional SQLA session object (a temporary one will be
@@ -1220,7 +1220,7 @@ __all__.append('PolicyQueue')
 @session_wrapper
 def get_policy_queue(queuename: str, session=None) -> Optional[PolicyQueue]:
     """
-    Returns PolicyQueue object for given C{queue name}
+    Returns PolicyQueue object for given `queuename`
 
     :param queuename: The name of the queue
     :param session: Optional SQLA session object (a temporary one will be
@@ -1299,7 +1299,7 @@ __all__.append('Priority')
 @session_wrapper
 def get_priority(priority: str, session=None) -> Optional[Priority]:
     """
-    Returns Priority object for given C{priority name}.
+    Returns Priority object for given `priority` name.
 
     :param priority: The name of the priority
     :param session: Optional SQLA session object (a temporary one will be
@@ -1345,7 +1345,7 @@ __all__.append('Section')
 @session_wrapper
 def get_section(section: str, session=None) -> Optional[Section]:
     """
-    Returns Section object for given C{section name}.
+    Returns Section object for given `section` name.
 
     :param section: The name of the section
     :param session: Optional SQLA session object (a temporary one will be
@@ -1486,7 +1486,7 @@ __all__.append('DBSource')
 @session_wrapper
 def get_suites_source_in(source: str, session=None) -> 'list[Suite]':
     """
-    Returns list of Suite objects which given C{source} name is in
+    Returns list of Suite objects which given `source` name is in
 
     :param source: DBSource package name to search for
     :return: list of Suite objects for the given source
@@ -1504,14 +1504,11 @@ __all__.append('get_suites_source_in')
 @session_wrapper
 def get_source_in_suite(source: str, suite_name: Optional[str], session=None) -> Optional[DBSource]:
     """
-    Returns a DBSource object for a combination of C{source} and C{suite_name}.
-
-      - B{source} - source package name, eg. I{mailfilter}, I{bbdb}, I{glibc}
-      - B{suite_name} - a suite name, eg. I{unstable}
+    Returns a DBSource object for a combination of `source` and `suite_name`.
 
     :param source: source package name
     :param suite_name: the suite name
-    :return: the version for I{source} in I{suite}
+    :return: the version for `source` in `suite`
     """
     suite = get_suite(suite_name, session)
     if suite is None:
@@ -1637,9 +1634,7 @@ class Suite(ORMObject):
 
     def get_sources(self, source: str) -> sqlalchemy.orm.query.Query:
         """
-        Returns a query object representing DBSource that is part of C{suite}.
-
-          - B{source} - source package name, eg. I{mailfilter}, I{bbdb}, I{glibc}
+        Returns a query object representing DBSource that is part of this suite.
 
         :param source: source package name
         :return: a query of DBSource
@@ -1675,7 +1670,7 @@ __all__.append('Suite')
 @session_wrapper
 def get_suite(suite: str, session=None) -> Optional[Suite]:
     """
-    Returns Suite object for given C{suite name}.
+    Returns Suite object for given `suite` name.
 
     :param suite: The name of the suite
     :param session: Optional SQLA session object (a temporary one will be
@@ -1710,8 +1705,8 @@ __all__.append('get_suite')
 @session_wrapper
 def get_suite_architectures(suite: str, skipsrc: bool = False, skipall: bool = False, session=None) -> list[Architecture]:
     """
-    Returns list of Architecture objects for given C{suite} name. The list is
-    empty if suite does not exist.
+    Returns list of Architecture objects for given `suite` name. The list is
+    empty if `suite` does not exist.
 
     :param suite: Suite name to search for
     :param skipsrc: Whether to skip returning the 'source' architecture entry

daklib/fstransactions.py

@@ -130,13 +130,13 @@ class FilesystemTransaction:
         self.actions = []
 
     def copy(self, source: str, destination: str, link: bool = False, symlink: bool = False, mode: Optional[int] = None) -> None:
-        """copy C{source} to C{destination}
+        """copy `source` to `destination`
 
         :param source: source file
         :param destination: destination file
         :param link: try hardlinking, falling back to copying
         :param symlink: create a symlink instead of copying
-        :param mode: permissions to change C{destination} to
+        :param mode: permissions to change `destination` to
         """
         if isinstance(mode, str):
             mode = int(mode, 8)
@@ -144,24 +144,24 @@ class FilesystemTransaction:
         self.actions.append(_FilesystemCopyAction(source, destination, link=link, symlink=symlink, mode=mode))
 
     def move(self, source: str, destination: str, mode: Optional[int] = None) -> None:
-        """move C{source} to C{destination}
+        """move `source` to `destination`
 
         :param source: source file
         :param destination: destination file
-        :param mode: permissions to change C{destination} to
+        :param mode: permissions to change `destination` to
         """
         self.copy(source, destination, link=True, mode=mode)
         self.unlink(source)
 
     def unlink(self, path: str) -> None:
-        """unlink C{path}
+        """unlink `path`
 
         :param path: file to unlink
         """
         self.actions.append(_FilesystemUnlinkAction(path))
 
     def create(self, path: str, mode: Optional[int] = None, text: bool = True) -> IO:
-        """create C{filename} and return file handle
+        """create `filename` and return file handle
 
         :param path: file to create
         :param mode: permissions for the new file

daklib/lintian.py

@@ -68,7 +68,7 @@ def generate_reject_messages(parsed_tags, tag_definitions, log=lambda *args: arg
     Generates package reject messages by comparing parsed lintian output with
     tag definitions. Returns a generator containing the reject messages.
 
-    :param parsed_tags: Parsed lintian tags as returned by L{parse_lintian_output}
+    :param parsed_tags: Parsed lintian tags as returned by :func:`parse_lintian_output`
     :param tag_definitions: YAML.load lintian tag definitions to reject on
 
     :return: Reject message(s), if any

daklib/policy.py

@@ -38,8 +38,8 @@ class UploadCopy:
           ...
 
     Doing so will provide a temporary copy of the upload in the directory
-    given by the C{directory} attribute.  The copy will be removed on leaving
-    the with-block.
+    given by the :attr:`directory` attribute.  The copy will be removed
+    on leaving the with-block.
     """
 
     def __init__(self, upload: PolicyQueueUpload, group=None):

daklib/queue.py

@@ -51,7 +51,7 @@ def check_valid(overrides: list[dict], session) -> bool:
                       - type: type of requested override ('dsc', 'deb' or 'udeb')
 
                       All values are strings.
-    :return: C{True} if all overrides are valid, C{False} if there is any
+    :return: :const:`True` if all overrides are valid, :const:`False` if there is any
              invalid override.
     """
     all_valid = True

daklib/upload.py

@@ -17,7 +17,7 @@
 """module to handle uploads not yet installed to the archive
 
 This module provides classes to handle uploads not yet installed to the
-archive.  Central is the L{Changes} class which represents a changes file.
+archive.  Central is the :class:`Changes` class which represents a changes file.
 It provides methods to access the included binary and source packages.
 """
 
@@ -118,10 +118,10 @@ class HashedFile:
         """SHA256 hash in hexdigits"""
 
         self.section: Optional[str] = section
-        """section or C{None}"""
+        """section or :const:`None`"""
 
         self.priority: Optional[str] = priority
-        """priority or C{None}"""
+        """priority or :const:`None`"""
 
     @classmethod
     def from_file(cls, directory: str, filename: str, section: Optional[str] = None, priority: Optional[str] = None) -> 'HashedFile':
@@ -187,7 +187,7 @@ def parse_file_list(
     :param control: control file to take fields from
     :param has_priority_and_section: Files field include section and priority
                                      (as in .changes)
-    :return: dict mapping filenames to L{daklib.upload.HashedFile} objects
+    :return: dict mapping filenames to :class:`HashedFile` objects
 
     :raises InvalidChangesException: missing fields or other grave errors
     """
@@ -285,12 +285,12 @@ class Changes:
 
     @property
     def valid_signature(self) -> bool:
-        """C{True} if the .changes has a valid signature"""
+        """:const:`True` if the .changes has a valid signature"""
         return self.signature.valid
 
     @property
     def weak_signature(self) -> bool:
-        """C{True} if the .changes was signed using a weak algorithm"""
+        """:const:`True` if the .changes was signed using a weak algorithm"""
         return self.signature.weak_signature
 
     @property
@@ -313,7 +313,7 @@ class Changes:
 
     @property
     def source(self) -> 'Optional[Source]':
-        """included source or C{None}"""
+        """included source or :const:`None`"""
         if self._source is None:
             source_files = []
             for f in self.files.values():
@@ -325,7 +325,7 @@ class Changes:
 
     @property
     def sourceful(self) -> bool:
-        """C{True} if the upload includes source"""
+        """:const:`True` if the upload includes source"""
         return "source" in self.architectures
 
     @property
@@ -382,7 +382,7 @@ class Changes:
 
     @property
     def files(self) -> dict[str, HashedFile]:
-        """dict mapping filenames to L{daklib.upload.HashedFile} objects"""
+        """dict mapping filenames to :class:`HashedFile` objects"""
         if self._files is None:
             self._files = parse_file_list(self.changes, True)
         return self._files
@@ -510,7 +510,7 @@ class Source:
 
     @property
     def files(self) -> dict[str, HashedFile]:
-        """dict mapping filenames to L{HashedFile} objects for additional source files
+        """dict mapping filenames to :class:`HashedFile` objects for additional source files
 
         This list does not include the .dsc itself.
         """
@@ -525,12 +525,12 @@ class Source:
 
     @property
     def valid_signature(self) -> bool:
-        """C{True} if the .dsc has a valid signature"""
+        """:const:`True` if the .dsc has a valid signature"""
         return self.signature.valid
 
     @property
     def weak_signature(self) -> bool:
-        """C{True} if the .dsc was signed using a weak algorithm"""
+        """:const:`True` if the .dsc was signed using a weak algorithm"""
         return self.signature.weak_signature
 
     @property

daklib/utils.py

@@ -217,8 +217,8 @@ def check_dsc_files(dsc_filename: str, dsc: Mapping[str, str], dsc_files: Mappin
     those expected given the announced Format.
 
     :param dsc_filename: path of .dsc file
-    :param dsc: the content of the .dsc parsed by C{parse_changes()}
-    :param dsc_files: the file list returned by C{build_file_list()}
+    :param dsc: the content of the .dsc parsed by :func:`parse_changes`
+    :param dsc_files: the file list returned by :func:`build_file_list`
     :return: all errors detected
     """
     rejmsg = []
@@ -329,7 +329,7 @@ def build_file_list(changes, is_a_dsc: bool = False, field="files", hashname="md
 def send_mail(message, whitelists: Optional[list[Optional[str]]] = None) -> None:
     """sendmail wrapper, takes a message string
 
-    :param whitelists: path to whitelists. C{None} or an empty list whitelists
+    :param whitelists: path to whitelists. :const:`None` or an empty list whitelists
                        everything, otherwise an address is whitelisted if it is
                        included in any of the lists.
                        In addition a global whitelist can be specified in

dakweb/__init__.py

 """
 General
 =======
-  The Debian Archive Kit web api, AKA the B{FTP-Master api}, allows
+  The Debian Archive Kit web api, AKA the **FTP-Master api**, allows
   anyone to query the database of the Debian archive kit for information
   related to the archive. That is, it provides information about the
   archive, its suites and all the packages.
 
   Development
   -----------
-  B{NOTE}: B{The api} is still new and we are adding new features
-  whenever someone asks for them. Or better yet, provides a patch.
-  B{The api}s code lives in the C{dak} codebase, if you want to provide
-  a patch with a new feature, or fix a bug, feel free to fork it on
-  Salsa and send us a merge request::
 
-  https://salsa.debian.org/ftp-team/dak/
+  .. note::
+
+     The API is still new and we are adding new features
+     whenever someone asks for them. Or better yet, provides a patch.
+     The APIs code lives in the DAK codebase, if you want to provide
+     a patch with a new feature, or fix a bug, feel free to fork it on
+     Salsa and send us a merge request::
+
+     https://salsa.debian.org/ftp-team/dak/
 
 Usage
 =====
-  B{The api} responds to simple http queries and (usually) replies with
+  The API responds to simple http queries and (usually) replies with
   JSON formatted data. Some commands may require an extra parameter to
   output JSON (notably the madison one).
 
-  U{https://api.ftp-master.debian.org/} is the base path for all
+  ``https://api.ftp-master.debian.org/`` is the base path for all
   requests.
 
   Available Methods
   -----------------
   The list of available methods can be seen by browsing the
-  automatically generated documentation for the L{dakweb.queries}
+  automatically generated documentation for the :mod:`dakweb.queries`
   module. There are various submodules dealing with different parts of
-  the api. Every I{public} function of those modules corresponds to
+  the api. Every *public* function of those modules corresponds to
   one available method. The input parameters and the output format are
   documented with each of those functions.
 

dakweb/queries/madison.py

@@ -16,7 +16,7 @@ from dakweb.webregister import QueryRegister
 @bottle.route('/madison')
 def madison():
     """
-    Display information about B{package(s)}.
+    Display information about `package`\ (s).
 
     .. versionadded:: December 2014
 
@@ -27,9 +27,10 @@ def madison():
     @keyword s: only show info for this suite.
     @keyword S: show info for the binary children of source pkgs. I{true/false}
     @keyword f: output json format. I{json}
-    @see: L{I{suites}<dakweb.queries.suite.suites>} on how to receive a list of valid suites.
 
     :return: Text or Json format of the data
+
+    .. seealso:: :func:`~dakweb.queries.suite.suites` on how to receive a list of valid suites.
     """
 
     r = bottle.request

dakweb/queries/source.py

@@ -23,7 +23,6 @@ def dsc_in_suite(suite: Optional[str] = None, source: Optional[str] = None) -> s
     .. versionadded: December 2014
 
     :param suite: Name of the suite.
-       @see: L{I{suites}<dakweb.queries.suite.suites>} on how to receive a list of valid suites.
     :param source: Source package to query for.
     :return: List of dictionaries made out of
              - version
@@ -31,6 +30,8 @@ def dsc_in_suite(suite: Optional[str] = None, source: Optional[str] = None) -> s
              - filename
              - filesize
              - sha256sum
+
+    .. seealso:: :func:`~dakweb.queries.suite.suites` on how to receive a list of valid suites.
     """
     if suite is None:
         return bottle.HTTPError(503, 'Suite not specified.')
@@ -144,10 +145,11 @@ def sources_in_suite(suite: Optional[str] = None) -> str:
     .. versionadded:: December 2014
 
     :param suite: Name of the suite.
-       @see: L{I{suites}<dakweb.queries.suite.suites>} on how to receive a list of valid suites.
     :return: List of dictionaries made out of
              - source
              - version
+
+    .. seealso:: :func:`~dakweb.queries.suite.suites` on how to receive a list of valid suites.
     """
     if suite is None:
         return bottle.HTTPError(503, 'Suite not specified.')

dakweb/queries/suite.py

@@ -64,7 +64,6 @@ def suite(suite: Optional[str] = None) -> str:
     names.
 
     :param suite: Name or codename of the suite.
-      @see: L{I{suites}<dakweb.queries.suite.suites>} on how to receive a list of valid suites.
 
     :return: A dictionary of
              - name: maps to `Suite:` in the Release file
@@ -73,6 +72,8 @@ def suite(suite: Optional[str] = None) -> str:
              - archive
              - architectures
              - components
+
+    .. seealso:: :func:`~dakweb.queries.suite.suites` on how to receive a list of valid suites.
     """
 
     if suite is None: