Minor doc improvements for recent changes

- Add missing CHANGELOG entry for new API

- Fix mispelled ModulemdDefaultsUnit class in docs

- Add all the SyncOptions classes into docs

- Fix wrong copy-pasted summary on YumSyncOptions

- Add "versionadded" a few places for sync to help record which
  minimum version is needed to use this feature

- Add a "seealso" on SyncOptions to help find the other related
  classes

- Fix links from SyncOptions back to sync method (linking to
  inherited sync() method on repository subclasses doesn't seem to
  work)

- Tweak how the default argument to sync() is set; it's functionally
  equivalent to how it was before, but renders more nicely in docs.

CHANGELOG.md

@@ -7,7 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-- N/A
+### Added
+- Introduced `Repository.sync` API (and associated `SyncOptions` classes)
+  for synchronizing Pulp repositories.
 
 ## [2.4.0] - 2020-01-13
 

docs/api/model.rst

@@ -21,18 +21,31 @@ Repository
 .. autoclass:: pubtools.pulplib.YumRepository()
    :members:
 
+.. autoclass:: pubtools.pulplib.YumSyncOptions()
+   :members:
+
 .. autoclass:: pubtools.pulplib.FileRepository()
    :members:
 
+.. autoclass:: pubtools.pulplib.FileSyncOptions()
+   :members:
+
 .. autoclass:: pubtools.pulplib.ContainerImageRepository()
    :members:
 
+.. autoclass:: pubtools.pulplib.ContainerSyncOptions()
+   :members:
+
 .. autoclass:: pubtools.pulplib.Distributor()
    :members:
 
 .. autoclass:: pubtools.pulplib.PublishOptions()
    :members:
 
+.. autoclass:: pubtools.pulplib.SyncOptions()
+   :members:
+
+
 
 Units
 -----
@@ -49,7 +62,7 @@ Units
 .. autoclass:: pubtools.pulplib.ModulemdUnit()
    :members:
 
-.. autoclass:: pubtools.pulplib.ModulemdDefaultUnit()
+.. autoclass:: pubtools.pulplib.ModulemdDefaultsUnit()
    :members:
 
 Task

pubtools/pulplib/_impl/fake/controller.py

@@ -126,6 +126,8 @@ def sync_history(self):
                 of this sync
             ``sync_config``:
                 :class:`~pubtools.pulplib.SyncConfig` (of the appropriate subclass) used for this sync
+
+        .. versionadded:: 2.5.0
         """
         return self.client._sync_history[:]
 

pubtools/pulplib/_impl/model/repository/base.py

@@ -62,6 +62,11 @@ class PublishOptions(object):
 class SyncOptions(object):
     """Options controlling a repository
     :meth:`~pubtools.pulplib.Repository.sync`.
+
+    .. seealso:: Subclasses for specific repository
+                 types: :py:class:`~pubtools.pulplib.FileSyncOptions`,
+                 :py:class:`~pubtools.pulplib.YumSyncOptions`,
+                 :py:class:`~pubtools.pulplib.ContainerSyncOptions`
     """
 
     feed = pulp_attrib(type=str)
@@ -388,8 +393,8 @@ def publish(self, options=PublishOptions()):
 
         return f_proxy(self._client._publish_repository(self, to_publish))
 
-    def sync(self, options=SyncOptions(feed="")):
-        """Sync repository with feed
+    def sync(self, options=None):
+        """Sync repository with feed.
 
         Args:
             options (SyncOptions)
@@ -406,7 +411,11 @@ def sync(self, options=SyncOptions(feed="")):
         Raises:
             DetachedException
                 If this instance is not attached to a Pulp client.
+
+        .. versionadded:: 2.5.0
         """
+        options = options or SyncOptions(feed="")
+
         if not self._client:
             raise DetachedException()
 

pubtools/pulplib/_impl/model/repository/container.py

@@ -6,7 +6,7 @@
 @attr.s(kw_only=True, frozen=True)
 class ContainerSyncOptions(SyncOptions):
     """Options controlling a container repository
-    :meth:`~pubtools.pulplib.ContainerImageRepository.sync`.
+    :meth:`~pubtools.pulplib.Repository.sync`.
     """
 
     upstream_name = pulp_attrib(default=None, type=str)

pubtools/pulplib/_impl/model/repository/file.py

@@ -17,7 +17,7 @@
 @attr.s(kw_only=True, frozen=True)
 class FileSyncOptions(SyncOptions):
     """Options controlling a file repository
-    :meth:`~pubtools.pulplib.FileRepository.sync`.
+    :meth:`~pubtools.pulplib.Repository.sync`.
     """
 
     remove_missing = pulp_attrib(default=False, type=bool)

pubtools/pulplib/_impl/model/repository/yum.py

@@ -6,8 +6,8 @@
 
 @attr.s(kw_only=True, frozen=True)
 class YumSyncOptions(SyncOptions):
-    """Options controlling a container repository
-    :meth:`~pubtools.pulplib.YumRepository.sync`.
+    """Options controlling a yum repository
+    :meth:`~pubtools.pulplib.Repository.sync`.
     """
 
     query_auth_token = pulp_attrib(default=None, type=str)