Minor fixes to the docstrings to make Sphinx look pretty.

Author: LTLA

src/pygobbler/allocate_upload_directory.py

@@ -1,7 +1,7 @@
 def allocate_upload_directory(staging: str) -> str:
     """
     Allocate a subdirectory in the staging directory to prepare files for
-    upload via :py:func:`~upload_directory.upload_directory`.
+    upload via :py:func:`~.upload_directory`.
 
     Args:
         staging:

src/pygobbler/clone_version.py

@@ -11,9 +11,9 @@ def clone_version(project: str, asset: str, version: str, destination: str, regi
     that has the same structure as that of the specified project-asset-version.
     All files in the version are represented as symlinks from ``destination``
     to the corresponding file in the ``registry``.The idea is that, when
-    ``destination`` is used in :py:func:`~upload_directory.upload_directory`,
-    the symlinks are converted into upload links. This allows users to create
-    new versions very cheaply as duplicate files are not stored in the backend.
+    ``destination`` is used in :py:func:`~.upload_directory`, the symlinks are
+    converted into upload links. This allows users to create new versions very
+    cheaply as duplicate files are not stored in the backend.
 
     Users can more-or-less do whatever they want inside the cloned ``destination``,
     but the symlink targets should be read-only as they refer to immutable files in

src/pygobbler/create_project.py

@@ -22,9 +22,8 @@ def create_project(project: str, staging: str, url: str, owners: Optional[List]
 
         uploaders:
             List specifying the authorized uploaders for this project. See the
-            ``uploaders`` field in
-            :py:func:`~fetch_permissions.fetch_permissions` return value for
-            the the expected format. 
+            ``uploaders`` field in :py:func:`~.fetch_permissions` return value
+            for the expected format. 
 
     Returns:
         On success, the requested project is created in the registry.

src/pygobbler/fetch_permissions.py

@@ -30,16 +30,16 @@ def fetch_permissions(project: str, registry: str, url: str, force_remote: bool
         dictionary has the following fields:
 
         - ``id``, string containing a user ID that is authorized to upload.
-        - (optional) ``asset``, string containing the name of the asset that
+        - ``asset`` (optional), string containing the name of the asset that
           the uploader is allowed to upload to. If not present, there is no
           restriction on the uploaded asset name.
-        - (optional) ``version``, string containing the name of the version
+        - ``version`` (optional), string containing the name of the version
           that the uploader is allowed to upload to. If not present, there is
           no restriction on the uploaded version name.
-        - (optional) ``until``, string containing the expiry date of this
+        - ``until`` (optional), string containing the expiry date of this
           authorization in Internet Date/Time format. If not provided, the
           authorization does not expire.
-        - (optional) ``trusted``, whether the uploader is trusted. If not
+        - ``trusted`` (optional), whether the uploader is trusted. If not
           provided, defaults to false.
     """
     if os.path.exists(registry) and not force_remote:

src/pygobbler/fetch_summary.py

@@ -39,12 +39,12 @@ def fetch_summary(project: str, asset: str, version: str, registry: str, url: st
     Returns:
         Dictionary containing summary information including:
 
-        - `uploader_user_id`, string containing the UID of the uploading user.
-        - `upload_start_time`, string containing the upload start time in
+        - ``uploader_user_id``, string containing the UID of the uploading user.
+        - ``upload_start_time``, string containing the upload start time in
           Internet Date/Time format.
-        - `upload_finish_time`, string containing the upload finish time in
+        - ``upload_finish_time``, string containing the upload finish time in
           Internet Date/Time format.
-        - `probation` (optional), boolean indicating whether this version of
+        - ``on_probation`` (optional), boolean indicating whether this version of
           the asset is a probational upload.
     """
 

src/pygobbler/set_permissions.py

@@ -27,8 +27,8 @@ def set_permissions(project: str, registry: str, staging: str, url: str, owners:
         uploaders:
             List of dictionaries specifying the authorized uploaders for this
             project.  See the ``uploaders`` field in the return value of
-            :py:func:`~fetch_permissions.fetch_permissions` for  the expected
-            format. If None, no change is made to the existing uploaders.
+            :py:func:`~.fetch_permissions` for  the expected format. If None,
+            no change is made to the existing uploaders.
 
         append:
             Whether ``owners`` and ``uploaders`` should be appended to the

src/pygobbler/start_gobbler.py

@@ -23,15 +23,24 @@ def start_gobbler(staging: Optional[str] = None, registry: Optional[str] = None,
             automatically created.
 
         port:
-            Port number for the Gobbler API to receive requests.
+            Port number for the Gobbler API to receive requests. If None, an
+            open port is automatically chosen.
 
         wait:
             Number of seconds to wait for the service to initialize before use.
 
+        version:
+            Version of the service to run.
+
+        overwrite:
+            Whether to overwrite the existing Gobbler binary.
+
     Returns:
         A tuple indicating whether a new test service was created (or an
-        existing instance was re-used), the path to the staging directory, 
-        the path to the registry, and the chosen URL.
+        existing instance was re-used), the path to the staging directory, the
+        path to the registry, and the chosen URL. If a service is already
+        running, this function is a no-op and the configuration details of the
+        existing service will be returned.
     """
     global test_staging
     global test_registry
@@ -130,9 +139,8 @@ def _initialize_gobbler_process(exe: str, staging: Optional[str], registry: Opti
 
 def stop_gobbler():
     """
-    Stop any existing gobbler test service. This will also reset any URL that
-    was modified by :py:func:`~start_gobbler`. If no test service was running,
-    this function is a no-op.
+    Stop any gobbler test service started by :py:func:`~.start_gobbler`. If no
+    test service was running, this function is a no-op.
     """
     global test_process 
     if test_process is not None:

src/pygobbler/upload_directory.py

@@ -18,10 +18,9 @@ def upload_directory(project: str, asset: str, version: str, directory: str, sta
             The name of a new version of ``asset``.
 
         directory:
-            Path to a directory to be uploaded. This should be a subdirectory
-            of ``staging`` for best performance, see
-            :py:func:`~allocate_upload_directory.allocate_upload_directory` for
-            details.
+            Path to a directory to be uploaded. For best performace, this
+            should be a subdirectory of ``staging``, e.g., as created by
+            :py:func:`~.allocate_upload_directory`.
 
         staging:
             Path to the staging directory.

src/pygobbler/version_path.py

@@ -16,7 +16,7 @@ def version_path(project, asset, version, **kwargs) -> str:
             The name of the version of the ``asset`` to obtain.
 
         kwargs:
-            Further arguments to :py:func:`~fetch_directory.fetch_directory`.
+            Further arguments to :py:func:`~.fetch_directory`.
 
     Returns:
         The path to the directory containing the desired version.