feat: immprove help messages for all cli commands

fastanime/cli/__init__.py

@@ -38,6 +38,29 @@ signal.signal(signal.SIGINT, handle_exit)
     cls=LazyGroup,
     help="A command line application for streaming anime that provides a complete and featureful interface",
     short_help="Stream Anime",
+    epilog="""
+\b
+\b\bExamples:
+  # example of syncplay intergration
+  fastanime --sync-play --server sharepoint search -t <anime-title>
+\b
+  # --- or ---
+\b
+  # to watch with anilist intergration
+  fastanime --sync-play --server sharepoint anilist
+\b
+  # downloading dubbed anime
+  fastanime --dub download -t <anime>
+\b
+  # use  icons and fzf for a more elegant ui with preview
+  fastanime --icons --preview --fzf anilist
+\b
+  # use icons with default ui
+  fastanime --icons --default anilist
+\b
+  # viewing manga
+  fastanime --manga search -t <manga-title> 
+""",
 )
 @click.version_option(__version__, "--version")
 @click.option("--manga", "-m", help="Enable manga mode", is_flag=True)

fastanime/cli/commands/anilist/__init__.py

@@ -30,6 +30,53 @@ commands = {
     invoke_without_command=True,
     help="A beautiful interface that gives you access to a commplete streaming experience",
     short_help="Access all streaming options",
+    epilog="""
+\b
+\b\bExamples:
+  # ---- search ----  
+\b
+  # get anime with the tag of isekai
+  fastanime anilist search -T isekai
+\b
+  # get anime of 2024 and sort by popularity
+  # that has already finished airing or is releasing
+  # and is not in your anime lists
+  fastanime anilist search -y 2024 -s POPULARITY_DESC --status RELEASING --status FINISHED --not-on-list
+\b
+  # get anime of 2024 season WINTER
+  fastanime anilist search -y 2024 --season WINTER
+\b
+  # get anime genre action and tag isekai,magic
+  fastanime anilist search -g Action -T Isekai -T Magic
+\b
+  # get anime of 2024 thats finished airing
+  fastanime anilist search -y 2024 -S FINISHED
+\b
+  # get the most favourite anime movies
+  fastanime anilist search -f MOVIE -s FAVOURITES_DESC
+\b
+  # ---- login ----
+\b
+  # To sign in just run 
+  fastanime anilist login
+\b
+  # To view your login status 
+  fastanime anilist login --status
+\b
+  # To erase login data
+  fastanime anilist login --erase
+\b
+  # ---- notifier ----  
+\b
+  # basic form
+  fastanime anilist notifier
+\b
+  # with logging to stdout
+  fastanime --log anilist notifier
+\b
+  # with logging to a file. stored in the same place as your config
+  fastanime --log-file anilist notifier
+""",
 )
 @click.pass_context
 def anilist(ctx: click.Context):

fastanime/cli/commands/cache.py

@@ -1,7 +1,24 @@
 import click
 
 
-@click.command(help="Helper command to manage cache")
+@click.command(
+    help="Helper command to manage cache",
+    epilog="""
+\b
+\b\bExamples:
+  # delete everything in the cache dir
+  fastanime cache --clean
+\b
+  # print the path to the cache dir and exit
+  fastanime cache --path
+\b
+  # print the current size of the cache dir and exit
+  fastanime cache --size
+\b
+  # open the cache dir and exit
+  fastanime cache
+""",
+)
 @click.option("--clean", help="Clean the cache dir", is_flag=True)
 @click.option("--path", help="The path to the cache dir", is_flag=True)
 @click.option("--size", help="The size of the cache dir", is_flag=True)

fastanime/cli/commands/completions.py

@@ -1,7 +1,24 @@
 import click
 
 
-@click.command(help="Helper command to get shell completions")
+@click.command(
+    help="Helper command to get shell completions",
+    epilog="""
+\b
+\b\bExamples:
+    # try to detect your shell and print completions
+    fastanime completions
+\b
+    # print fish completions
+    fastanime completions --fish
+\b
+    # print bash completions
+    fastanime completions --bash
+\b
+    # print zsh completions
+    fastanime completions --zsh
+""",
+)
 @click.option("--fish", is_flag=True, help="print fish completions")
 @click.option("--zsh", is_flag=True, help="print zsh completions")
 @click.option("--bash", is_flag=True, help="print bash completions")

fastanime/cli/commands/config.py

@@ -9,6 +9,25 @@ if TYPE_CHECKING:
 @click.command(
     help="Manage your config with ease",
     short_help="Edit your config",
+    epilog="""
+\b
+\b\bExamples:
+  # Edit your config in your default editor 
+  # NB: If it opens vim or vi exit with `:q`
+  fastanime config
+\b
+  # get the path of the config file
+  fastanime config --path
+\b
+  # print desktop entry info
+  fastanime config --desktop-entry
+\b
+  # update your config without opening an editor
+  fastanime --icons --fzf --preview config --update
+\b 
+  # view the current contents of your config
+  fastanime config --view
+""",
 )
 @click.option("--path", "-p", help="Print the config location and exit", is_flag=True)
 @click.option(
@@ -94,7 +113,7 @@ def config(user_config: "Config", path, view, desktop_entry, update):
                 print(f"Successfully wrote \n{f.read()}")
                 exit_app(0)
     elif update:
-        with open(USER_CONFIG_PATH, "w",encoding="utf-8") as file:
+        with open(USER_CONFIG_PATH, "w", encoding="utf-8") as file:
             file.write(user_config.__str__())
         print("update successfull")
     else:

fastanime/cli/commands/download.py

@@ -11,6 +11,53 @@ if TYPE_CHECKING:
 @click.command(
     help="Download anime using the anime provider for a specified range",
     short_help="Download anime",
+    epilog="""
+\b
+\b\bExamples:
+  # Download all available episodes
+  # multiple titles can be specified with -t option
+  fastanime download -t <anime-title> -t <anime-title>
+  # -- or --
+  fastanime download -t <anime-title> -t <anime-title> -r ':'
+\b
+  # download latest episode for the two anime titles
+  # the number can be any no of latest episodes but a minus sign
+  # must be present
+  fastanime download -t <anime-title> -t <anime-title> -r '-1'
+\b
+  # latest 5
+  fastanime download -t <anime-title> -t <anime-title> -r '-5'
+\b
+  # Download specific episode range
+  # be sure to observe the range Syntax
+  fastanime download -t <anime-title> -r '<episodes-start>:<episodes-end>:<step>'
+\b
+  fastanime download -t <anime-title> -r '<episodes-start>:<episodes-end>'
+\b
+  fastanime download -t <anime-title> -r '<episodes-start>:'
+\b
+  fastanime download -t <anime-title> -r ':<episodes-end>'
+\b
+  # download specific episode
+  # remember python indexing starts at 0
+  fastanime download -t <anime-title> -r '<episode-1>:<episode>'
+\b
+  # merge subtitles with ffmpeg to mkv format; aniwatch tends to give subs as separate files
+  # and dont prompt for anything
+  # eg existing file in destination instead remove
+  # and clean
+  # ie remove original files (sub file and vid file)
+  # only keep merged files
+  fastanime download -t <anime-title> --merge --clean --no-prompt
+\b
+  # EOF is used since -t always expects a title
+  # you can supply anime titles from file or -t at the same time
+  # from stdin
+  echo -e "<anime-title>\\n<anime-title>\\n<anime-title>" | fastanime download -t "EOF" -r <range> -f -
+\b
+  # from file
+  fastanime download -t "EOF" -r <range> -f <file-path>
+""",
 )
 @click.option(
     "--anime-titles",

fastanime/cli/commands/downloads.py

@@ -11,7 +11,32 @@ if TYPE_CHECKING:
 
 
 @click.command(
-    help="View and watch your downloads using mpv", short_help="Watch downloads"
+    help="View and watch your downloads using mpv",
+    short_help="Watch downloads",
+    epilog="""
+\b
+\b\bExamples:
+    fastanime downloads
+\b
+    # view individual episodes
+    fastanime downloads --view-episodes
+    # --- or ---
+    fastanime downloads -v
+\b
+    # to set seek time when using ffmpegthumbnailer for local previews
+    # -1 means random and is the default
+    fastanime downloads --time-to-seek <intRange(-1,100)>
+    # --- or ---
+    fastanime downloads -t <intRange(-1,100)>
+\b
+    # to watch a specific title
+    # be sure to get the completions for the best experience
+    fastanime downloads --title <title>
+\b
+    # to get the path to the downloads folder set
+    fastanime downloads --path
+    # useful when you want to use the value for other programs
+""",
 )
 @click.option("--path", "-p", help="print the downloads folder and exit", is_flag=True)
 @click.option(

fastanime/cli/commands/grab.py

@@ -11,6 +11,41 @@ if TYPE_CHECKING:
 @click.command(
     help="Helper command to get streams for anime to use externally in a non-python application",
     short_help="Print anime streams to standard out",
+    epilog="""
+\b
+\b\bExamples:
+  # --- print anime info + episode streams ---
+\b
+  # multiple titles can be specified with the -t option
+  fastanime grab -t <anime-title> -t <anime-title>
+  # -- or --
+  # print all available episodes
+  fastanime grab -t <anime-title> -r ':'
+\b
+  # print the latest episode
+  fastanime grab -t <anime-title> -r '-1'
+\b
+  # print a specific episode range
+  # be sure to observe the range Syntax
+  fastanime grab -t <anime-title> -r '<start>:<stop>'
+\b
+  fastanime grab -t <anime-title> -r '<start>:<stop>:<step>'
+\b
+  fastanime grab -t <anime-title> -r '<start>:'
+\b
+  fastanime grab -t <anime-title> -r ':<end>'
+\b
+  # --- grab options ---
+\b
+  # print search results only
+  fastanime grab -t <anime-title> -r <range> --search-results-only
+\b
+  # print anime info only
+  fastanime grab -t <anime-title> -r <range> --anime-info-only
+\b
+  # print episode streams only
+  fastanime grab -t <anime-title> -r <range> --episode-streams-only
+""",
 )
 @click.option(
     "--anime-titles",

fastanime/cli/commands/search.py

@@ -11,6 +11,29 @@ if TYPE_CHECKING:
 @click.command(
     help="This subcommand directly interacts with the provider to enable basic streaming. Useful for binging anime.",
     short_help="Binge anime",
+    epilog="""
+\b
+\b\bExamples:
+  # basic form where you will still be prompted for the episode number
+  # multiple titles can be specified with the -t option
+  fastanime search -t <anime-title> -t <anime-title>
+\b
+  # binge all episodes with this command
+  fastanime search -t <anime-title> -r ':'
+\b
+  # watch latest episode
+  fastanime search -t <anime-title> -r '-1'
+\b
+  # binge a specific episode range with this command
+  # be sure to observe the range Syntax
+  fastanime search -t <anime-title> -r '<start>:<stop>'
+\b
+  fastanime search -t <anime-title> -r '<start>:<stop>:<step>'
+\b
+  fastanime search -t <anime-title> -r '<start>:'
+\b
+  fastanime search -t <anime-title> -r ':<end>'
+""",
 )
 @click.option(
     "--anime-titles",

fastanime/cli/commands/update.py

@@ -1,7 +1,18 @@
 import click
 
 
-@click.command(help="Helper command to update fastanime to latest")
+@click.command(
+    help="Helper command to update fastanime to latest",
+    epilog="""
+\b
+\b\bExamples:
+  # update fastanime to latest
+  fastanime update
+\b
+  # check for latest release
+  fastanime update --check
+""",
+)
 @click.option("--check", "-c", help="Check for the latest release", is_flag=True)
 def update(
     check,