diff --git a/docs/conf.py b/docs/conf.py index 9c026c4b8..da9f2cda5 100644 --- a/docs/conf.py +++ b/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" diff --git a/semantic_release/cli/commands/version.py b/semantic_release/cli/commands/version.py index 503d7bf1e..5461cdd2d 100644 --- a/semantic_release/cli/commands/version.py +++ b/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") diff --git a/semantic_release/hvcs/gitea.py b/semantic_release/hvcs/gitea.py index 12f52e850..3ae2e6ab4 100644 --- a/semantic_release/hvcs/gitea.py +++ b/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 diff --git a/semantic_release/hvcs/gitlab.py b/semantic_release/hvcs/gitlab.py index f5452c4ca..1a9437b76 100644 --- a/semantic_release/hvcs/gitlab.py +++ b/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( diff --git a/semantic_release/hvcs/util.py b/semantic_release/hvcs/util.py index fd0d66ebc..3c4f78888 100644 --- a/semantic_release/hvcs/util.py +++ b/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()