docs: update docstrings to resolve sphinx failures

Fixes python-semantic-release#1029

- set `ignore-module-all` for `autodoc_default_options` to resolve some
  Sphinx errors about duplicate / ambiguous references
  sphinx-doc/sphinx#4961 (comment)
- Standardize some non-standard (Google-ish) docstrings to Sphinx
  format, to avoid ruff and Sphinx arguing about underline length.
- Fix indents and other minor whitespace / formatting changes.

docs/conf.py

@@ -16,6 +16,8 @@
     "sphinxcontrib.apidoc",
 ]
 
+autodoc_default_options = {"ignore-module-all": True}
+
 templates_path = ["_templates"]
 source_suffix = ".rst"
 master_doc = "index"

semantic_release/cli/commands/version.py

@@ -219,19 +219,12 @@ def build_distributions(
     """
     Run the build command to build the distributions.
 
-    Arguments:
-    ---------
-        build_command: str | None
-            The build command to run
-        build_command_env: Mapping[str, str] | None
-            The environment variables to use when running the build command
-        noop: bool
-            Whether or not to run the build command
-
-    Raises:
-    ------
-        BuildDistributionsError: if the build command fails
+    :param build_command: The build command to run.
+    :param build_command_env: The environment variables to use when running the
+        build command.
+    :param noop: Whether or not to run the build command.
 
+    :raises: BuildDistributionsError: if the build command fails
     """
     if not build_command:
         rprint("[green]No build command specified, skipping")

semantic_release/hvcs/gitea.py

@@ -95,11 +95,9 @@ def create_release(
         Ref: https://gitea.com/api/swagger#/repository/repoCreateRelease
 
         :param tag: Tag to create release for
-
         :param release_notes: The release notes for this version
-
         :param prerelease: Whether or not this release should be specified as a
-        prerelease
+            prerelease
 
         :return: Whether the request succeeded
         """
@@ -181,6 +179,7 @@ def get_release_id_by_tag(self, tag: str) -> int | None:
         Get a release by its tag name
         https://gitea.com/api/swagger#/repository/repoGetReleaseByTag
         :param tag: Tag to get release for
+
         :return: ID of found release
         """
         tag_endpoint = self.create_api_url(
@@ -206,6 +205,7 @@ def edit_release_notes(self, release_id: int, release_notes: str) -> int:
         https://gitea.com/api/swagger#/repository/repoEditRelease
         :param id: ID of release to update
         :param release_notes: The release notes for this version
+
         :return: The ID of the release that was edited
         """
         log.info("Updating release %s", release_id)
@@ -231,6 +231,7 @@ def create_or_update_release(
         Post release changelog
         :param version: The version number
         :param changelog: The release notes for this version
+
         :return: The status of the request
         """
         log.info("Creating release for %s", tag)
@@ -274,6 +275,7 @@ def upload_release_asset(
         :param release_id: ID of the release to upload to
         :param file: Path of the file to upload
         :param label: this parameter has no effect
+
         :return: The status of the request
         """
         url = self.asset_upload_url(release_id)
@@ -312,6 +314,7 @@ def upload_dists(self, tag: str, dist_glob: str) -> int:
         Upload distributions to a release
         :param tag: Tag to upload for
         :param path: Path to the dist directory
+
         :return: The number of distributions successfully uploaded
         """
         # Find the release corresponding to this tag

semantic_release/hvcs/gitlab.py

@@ -106,23 +106,16 @@ def create_release(
         """
         Create a release in a remote VCS, adding any release notes and assets to it
 
-        Arguments:
-        ---------
-            tag(str): The tag to create the release for
-            release_notes(str): The changelog description for this version only
-            prerelease(bool): This parameter has no effect in GitLab
-            assets(list[str]): A list of paths to files to upload as assets (TODO: not implemented)
-            noop(bool): If True, do not perform any actions, only log intents
-
-        Returns:
-        -------
-            str: The tag of the release
-
-        Raises:
-        ------
-            GitlabAuthenticationError: If authentication is not correct
-            GitlabCreateError: If the server cannot perform the request
+        :param tag: The tag to create the release for
+        :param release_notes: The changelog description for this version only
+        :param prerelease: This parameter has no effect in GitLab
+        :param assets: A list of paths to files to upload as assets (TODO: not implemented)
+        :param noop: If True, do not perform any actions, only log intents
 
+        :return: The tag of the release
+
+        :raises: GitlabAuthenticationError: If authentication is not correct
+        :raises: GitlabCreateError: If the server cannot perform the request
         """
         if noop:
             noop_report(f"would have created a release for tag {tag}")
@@ -145,20 +138,13 @@ def create_release(
     @suppress_not_found
     def get_release_by_tag(self, tag: str) -> gitlab.v4.objects.ProjectRelease | None:
         """
-        Get a release by its tag name
-
-        Arguments:
-        ---------
-            tag(str): The tag name to get the release for
+        Get a release by its tag name.
 
-        Returns:
-        -------
-            gitlab.v4.objects.ProjectRelease | None: The release object or None if not found
+        :param tag: The tag name to get the release for
 
-        Raises:
-        ------
-            gitlab.exceptions.GitlabAuthenticationError: If the user is not authenticated
+        :return: gitlab.v4.objects.ProjectRelease or None if not found
 
+        :raises: gitlab.exceptions.GitlabAuthenticationError: If the user is not authenticated
         """
         try:
             return self.project.releases.get(tag)
@@ -175,21 +161,15 @@ def edit_release_notes(  # type: ignore[override]
         release_notes: str,
     ) -> str:
         """
-        Update the release notes for a given release
+        Update the release notes for a given release.
 
-        Arguments:
-        ---------
-            release(gitlab.v4.objects.ProjectRelease): The release object to update
-            release_notes(str): The new release notes
+        :param release: The release object to update
+        :param release_notes: The new release notes
 
-        Returns:
-        -------
-            str: The release id
+        :return: The release id
 
-        Raises:
-        ------
-            GitlabAuthenticationError: If authentication is not correct
-            GitlabUpdateError: If the server cannot perform the request
+        :raises: GitlabAuthenticationError: If authentication is not correct
+        :raises: GitlabUpdateError: If the server cannot perform the request
 
         """
         log.info(
@@ -206,24 +186,17 @@ def create_or_update_release(
         self, tag: str, release_notes: str, prerelease: bool = False
     ) -> str:
         """
-        Create or update a release for the given tag in a remote VCS
-
-        Arguments:
-        ---------
-            tag(str): The tag to create or update the release for
-            release_notes(str): The changelog description for this version only
-            prerelease(bool): This parameter has no effect in GitLab
+        Create or update a release for the given tag in a remote VCS.
 
-        Returns:
-        -------
-            str: The release id
+        :param tag: The tag to create or update the release for
+        :param release_notes: The changelog description for this version only
+        :param prerelease: This parameter has no effect in GitLab
 
-        Raises:
-        ------
-            ValueError: If the release could not be created or updated
-            gitlab.exceptions.GitlabAuthenticationError: If the user is not authenticated
-            GitlabUpdateError: If the server cannot perform the request
+        :return: The release id
 
+        :raises ValueError: If the release could not be created or updated
+        :raises gitlab.exceptions.GitlabAuthenticationError: If the user is not authenticated
+        :raises GitlabUpdateError: If the server cannot perform the request
         """
         try:
             return self.create_release(

semantic_release/hvcs/util.py

@@ -21,12 +21,14 @@ def build_requests_session(
 ) -> Session:
     """
     Create a requests session.
+
     :param raise_for_status: If True, a hook to invoke raise_for_status be installed
     :param retry: If true, it will use default Retry configuration. if an integer, it
-                  will use default Retry configuration with given integer as total retry
-                  count. if Retry instance, it will use this instance.
+        will use default Retry configuration with given integer as total retry
+        count. if Retry instance, it will use this instance.
     :param auth: Optional TokenAuth instance to be used to provide the Authorization
-                 header to the session
+        header to the session
+
     :return: configured requests Session
     """
     session = Session()