dev(narugo): add more docs

docs/source/api_doc/entry/base.rst

@@ -0,0 +1,53 @@
+hfutils.entry.base
+================================
+
+.. currentmodule:: hfutils.entry.base
+
+.. automodule:: hfutils.entry.base
+
+
+CONTEXT_SETTINGS
+--------------------------
+
+.. autodata:: CONTEXT_SETTINGS
+
+
+
+ClickWarningException
+--------------------------------
+
+.. autoclass:: ClickWarningException
+    :members: exit_code, show
+
+
+
+ClickErrorException
+------------------------------------
+
+.. autoclass:: ClickErrorException
+    :members: exit_code, show
+
+
+
+print_exception
+----------------------------------
+
+.. autofunction:: print_exception
+
+
+
+KeyboardInterrupted
+------------------------------------
+
+.. autoclass:: KeyboardInterrupted
+    :members: __init__, exit_code, show
+
+
+
+command_wrap
+-------------------------------
+
+.. autofunction:: command_wrap
+
+
+

docs/source/api_doc/entry/cli.rst

@@ -0,0 +1,14 @@
+hfutils.entry.cli
+================================
+
+.. currentmodule:: hfutils.entry.cli
+
+.. automodule:: hfutils.entry.cli
+
+
+cli
+----------------------
+
+.. autodata:: cli
+
+

docs/source/api_doc/entry/dispatch.rst

@@ -0,0 +1,22 @@
+hfutils.entry.dispatch
+================================
+
+.. currentmodule:: hfutils.entry.dispatch
+
+.. automodule:: hfutils.entry.dispatch
+
+
+print_version
+----------------------------------------
+
+.. autofunction:: print_version
+
+
+
+hfutilcli
+----------------------------------------
+
+.. autofunction:: hfutilcli
+
+
+

docs/source/api_doc/entry/download.rst

@@ -0,0 +1,15 @@
+hfutils.entry.download
+================================
+
+.. currentmodule:: hfutils.entry.download
+
+.. automodule:: hfutils.entry.download
+
+
+NoRemotePathAssignedWithDownload
+--------------------------------------------
+
+.. autoclass:: NoRemotePathAssignedWithDownload
+    :members: exit_code, show
+
+

docs/source/api_doc/entry/index.rst

@@ -0,0 +1,17 @@
+hfutils.entry
+================================
+
+.. currentmodule:: hfutils.entry
+
+.. automodule:: hfutils.entry
+
+
+.. toctree::
+    :maxdepth: 3
+
+    base
+    cli
+    dispatch
+    download
+    upload
+

docs/source/api_doc/entry/upload.rst

@@ -0,0 +1,15 @@
+hfutils.entry.upload
+================================
+
+.. currentmodule:: hfutils.entry.upload
+
+.. automodule:: hfutils.entry.upload
+
+
+NoRemotePathAssignedWithUpload
+--------------------------------------
+
+.. autoclass:: NoRemotePathAssignedWithUpload
+    :members: exit_code, show
+
+

docs/source/index.rst

@@ -30,6 +30,7 @@ configuration file's structure and their versions.
 
     api_doc/archive/index
     api_doc/config/index
+    api_doc/entry/index
     api_doc/operate/index
     api_doc/utils/index
 

hfutils/entry/base.py

@@ -15,18 +15,50 @@
 
 
 class ClickWarningException(ClickException):
+    """
+    Custom exception class for displaying warnings in yellow color.
+
+    :param message: The error message.
+    :type message: str
+    """
+
     def show(self, file: Optional[IO] = None) -> None:
+        """
+        Display the warning message in yellow.
+
+        :param file: File to write the output to.
+        :type file: Optional[IO]
+        """
         click.secho(self.format_message(), fg='yellow', file=sys.stderr)
 
 
 class ClickErrorException(ClickException):
+    """
+    Custom exception class for displaying errors in red color.
+
+    :param message: The error message.
+    :type message: str
+    """
+
     def show(self, file: Optional[IO] = None) -> None:
+        """
+        Display the error message in red.
+
+        :param file: File to write the output to.
+        :type file: Optional[IO]
+        """
         click.secho(self.format_message(), fg='red', file=sys.stderr)
 
 
-# noinspection PyShadowingBuiltins
 def print_exception(err: BaseException, print: Optional[Callable] = None):
-    # noinspection PyShadowingBuiltins
+    """
+    Print exception information, including traceback.
+
+    :param err: The exception object.
+    :type err: BaseException
+    :param print: Custom print function. If not provided, uses built-in print.
+    :type print: Optional[Callable]
+    """
     print = print or builtins.print
 
     lines = list(itertools.chain(*map(
@@ -47,13 +79,34 @@ def print_exception(err: BaseException, print: Optional[Callable] = None):
 
 
 class KeyboardInterrupted(ClickWarningException):
+    """
+    Exception class for handling keyboard interruptions.
+
+    :param msg: Custom message to display.
+    :type msg: Optional[str]
+    """
     exit_code = 0x7
 
     def __init__(self, msg=None):
+        """
+        Initialize the exception.
+
+        :param msg: Custom message to display.
+        :type msg: Optional[str]
+        """
         ClickWarningException.__init__(self, msg or 'Interrupted.')
 
 
 def command_wrap():
+    """
+    Decorator for wrapping Click commands.
+
+    This decorator catches exceptions and provides consistent error handling.
+
+    :return: Decorator function.
+    :rtype: Callable
+    """
+
     def _decorator(func):
         @wraps(func)
         def _new_func(*args, **kwargs):

hfutils/entry/download.py

@@ -8,11 +8,23 @@
 from ..operate.base import REPO_TYPES, RepoTypeTyping
 
 
-class NoRemotePathAssigned(ClickErrorException):
+class NoRemotePathAssignedWithDownload(ClickErrorException):
+    """
+    Custom exception class for indicating that no remote path in the repository is assigned.
+    """
     exit_code = 0x11
 
 
 def _add_download_subcommand(cli: click.Group) -> click.Group:
+    """
+    Add the 'download' subcommand to the CLI.
+
+    :param cli: The Click CLI application.
+    :type cli: click.Group
+    :return: The modified Click CLI application.
+    :rtype: click.Group
+    """
+
     @cli.command('download', help='Download data from HuggingFace.\n\n'
                                   'Set environment $HF_TOKEN to use your own access token.',
                  context_settings=CONTEXT_SETTINGS)
@@ -34,9 +46,27 @@ def _add_download_subcommand(cli: click.Group) -> click.Group:
     def download(repo_id: str, repo_type: RepoTypeTyping,
                  file_in_repo: Optional[str], archive_in_repo: Optional[str], dir_in_repo: Optional[str],
                  output_path: str, revision: str):
+        """
+        Download data from HuggingFace repositories.
+
+        :param repo_id: Repository to download from.
+        :type repo_id: str
+        :param repo_type: Type of the HuggingFace repository.
+        :type repo_type: RepoTypeTyping
+        :param file_in_repo: File in repository to download.
+        :type file_in_repo: Optional[str]
+        :param archive_in_repo: Archive file in repository to download and extract from.
+        :type archive_in_repo: Optional[str]
+        :param dir_in_repo: Directory in repository to download the full directory tree.
+        :type dir_in_repo: Optional[str]
+        :param output_path: Output path for download.
+        :type output_path: str
+        :param revision: Revision of repository.
+        :type revision: str
+        """
         if not file_in_repo and not archive_in_repo and not dir_in_repo:
-            raise NoRemotePathAssigned('No remote path in repository assigned.\n'
-                                       'One of the -f, -a or -d option is required.')
+            raise NoRemotePathAssignedWithDownload('No remote path in repository assigned.\n'
+                                       'One of the -f, -a, or -d option is required.')
 
         if file_in_repo:
             if archive_in_repo:

hfutils/entry/upload.py

@@ -8,11 +8,23 @@
 from ..operate.base import REPO_TYPES, RepoTypeTyping, get_hf_client
 
 
-class NoRemotePathAssigned(ClickErrorException):
+class NoRemotePathAssignedWithUpload(ClickErrorException):
+    """
+    Custom exception class for indicating that no remote path in the repository is assigned.
+    """
     exit_code = 0x21
 
 
 def _add_upload_subcommand(cli: click.Group) -> click.Group:
+    """
+    Add the 'upload' subcommand to the CLI.
+
+    :param cli: The Click CLI application.
+    :type cli: click.Group
+    :return: The modified Click CLI application.
+    :rtype: click.Group
+    """
+
     @cli.command('upload', help='Upload data from HuggingFace.\n\n'
                                 'Set environment $HF_TOKEN to use your own access token.',
                  context_settings=CONTEXT_SETTINGS)
@@ -39,9 +51,32 @@ def _add_upload_subcommand(cli: click.Group) -> click.Group:
     def upload(repo_id: str, repo_type: RepoTypeTyping,
                file_in_repo: Optional[str], archive_in_repo: Optional[str], dir_in_repo: Optional[str],
                input_path: str, revision: str, clear: bool, private: bool):
+        """
+        Upload data to HuggingFace repositories.
+
+        :param repo_id: Repository to upload to.
+        :type repo_id: str
+        :param repo_type: Type of the HuggingFace repository.
+        :type repo_type: RepoTypeTyping
+        :param file_in_repo: File in repository to upload.
+        :type file_in_repo: Optional[str]
+        :param archive_in_repo: Archive file in repository to upload and extract from.
+        :type archive_in_repo: Optional[str]
+        :param dir_in_repo: Directory in repository to upload the full directory tree.
+        :type dir_in_repo: Optional[str]
+        :param input_path: Input path for upload.
+        :type input_path: str
+        :param revision: Revision of repository.
+        :type revision: str
+        :param clear: Clear the remote directory before uploading.
+                      Only applied when -d is used.
+        :type clear: bool
+        :param private: Use private repository when created.
+        :type private: bool
+        """
         if not file_in_repo and not archive_in_repo and not dir_in_repo:
-            raise NoRemotePathAssigned('No remote path in repository assigned.\n'
-                                       'One of the -f, -a or -d option is required.')
+            raise NoRemotePathAssignedWithUpload('No remote path in repository assigned.\n'
+                                       'One of the -f, -a, or -d option is required.')
 
         hf_client = get_hf_client()
         if not hf_client.repo_exists(repo_id, repo_type=repo_type):