From a513187d4842758e63fda6abd90c86d4f9d19928 Mon Sep 17 00:00:00 2001 From: V3n3RiX Date: Sat, 20 Jan 2024 18:49:09 +0000 Subject: rewrite help menus --- src/frontend/cli/sisyphus-cli.py | 356 +++++++++++++++++++-------------------- 1 file changed, 175 insertions(+), 181 deletions(-) diff --git a/src/frontend/cli/sisyphus-cli.py b/src/frontend/cli/sisyphus-cli.py index 253e192..93928c4 100755 --- a/src/frontend/cli/sisyphus-cli.py +++ b/src/frontend/cli/sisyphus-cli.py @@ -14,9 +14,10 @@ app.add_typer(mirrorSetup, name="mirror", @app.callback() def app_callback(ctx: typer.Context): - """Sisyphus is a simple python wrapper around portage, gentoolkit, and portage-utils - which provides an apt-get/yum-alike interface to these commands, - to assist newcomer people transitioning from Debian/RedHat-based systems to Gentoo. + """ + Sisyphus is a simple python wrapper around portage, gentoolkit, and portage-utils\n + which provides an apt-get/yum-alike interface to these commands, to assist newcomers\n + transitioning from Debian/RedHat-based systems to Gentoo.\n Use 'sisyphus COMMAND --help' for detailed usage. """ @@ -40,64 +41,48 @@ def search(package: List[str] = typer.Argument(...), quiet: bool = typer.Option( False, '-q', help='Short (one line) output.'), ebuild: bool = typer.Option(False, "--ebuild", "-e", help='Search in ebuilds (slower).')): - """Search for binary and/or ebuild (source) packages. - - By default will search for binary packages, using internal database. - The search term can be provided also in the category/name format, e.g: - - sisyphus search openbox - - OR - - sisyphus search x11-wm/openbox - - Using * and ? wildcards is supported. An empty string will match everything (similar to *). - - * Examples: - - to search for all packages belonging to a category, use '*' or leave the name empty: - - sisyphus search x11-wm/ - - sisyphus search x11-wm/* - - In addition, search can be performed by package description, using the -d (--description) option: - - sisyphus search x11/open -d 'window manager' - - (use single or double quotes when the description contains spaces) - - Use the -f (--filter) option to select only packages of interest. Possible values: - - all (default) - search the entire database - - alien - search for installed packages but not available - (this filter can match packages installed from e-builds or packages no longer maintained as binaries) - - installed - search in all installed packages - - available - search for available packages but not installed - - upgradable - search for installed packages where installed version is different from available version - - !!! NOTE !!!: - - bash will expand a single * character as current folder listing. - To search for all matching '--filter' packages escape it, or surround it with quotes, or use an empty string: - - sisyphus search * -f installed # this is not valid! - - sisyphus search \* -f alien # OK - - sisyphus search '*' -f available # OK - - sisyphus search '' -f upgradable # OK - - - To search for all (including source) packages, use the --ebuild option. - This is slower since will perform an emerge --search actually. - With this option, more than one package can be provided as search term. - '-d', '-f' and '-q' (quiet) options are ignored in this mode. + """Search for binary and/or ebuild (source) packages.\n + By default will search for binary packages, using internal database.\n + The search term can be provided also in the category/name format.\n + \n + * Examples:\n + sisyphus search openbox\n + sisyphus search x11-wm/openbox\n + \n + Using * and ? wildcards is supported. An empty string will match everything (similar to *).\n + \n + * Examples:\n + sisyphus search x11-wm/ # search all packages in the x11-wm category\n + sisyphus search x11-wm/* # search all packages in the x11-wm category\n + \n + In addition, search can be performed by package description, using the -d (--description) option:\n + \n + * Examples:\n + sisyphus search x11/open -d 'window manager' # use single or double quotes when the description contains spaces\n + \n + Use the -f (--filter) option to select only packages of interest. Possible values:\n + \n + all (default) - search the entire database\n + alien - search for installed packages but not available # (this filter can match packages installed from ebuilds or packages no longer maintained as binaries)\n + installed - search in all installed packages\n + available - search for available packages but not installed\n + upgradable - search for installed packages where installed version is different from available version\n + \n + !!! NOTE !!!\n + \n + Bash will expand a single * character as current folder listing.\n + To search for all matching '--filter' packages you need to escape it, surround it with quotes, or just use an empty string.\n + \n + * Examples:\n + sisyphus search * -f installed # not valid\n + sisyphus search \* -f alien # valid\n + sisyphus search '*' -f available # valid\n + sisyphus search '' -f upgradable # valid\n + \n + To search for all (including source) packages, use the --ebuild option.\n + This is slower since will perform an 'emerge --search' actually.\n + With this option, more than one package can be provided as search term.\n + '-d', '-f' and '-q' (quiet) options are ignored in this mode.\n """ if not ebuild: if '/' in package[0]: @@ -116,28 +101,26 @@ def search(package: List[str] = typer.Argument(...), @app.command("install") def install(pkgname: List[str], ebuild: bool = typer.Option( - False, "--ebuild", "-e", help='Install ebuild (source) package if binary package is not found (slower)'), - oneshot: bool = typer.Option(False, "--oneshot", "-1", help='Do not mark the package as explicitly installed, and do not add it to world set')): - """Install binary and/or ebuild(source) packages. - By default, only binary packages will be installed. - Use the --ebuild option to install ebuild(source) packages. - - * Examples: - - sisyphus install pidgin - - will install pidgin binary package (if available); if there is none, but the ebuild(source) package for pidgin is found, it will stop and suggest the --ebuild option. - - sisyphus install pidgin --ebuild - - will compile pidgin from source - - The --ebuild option will preffer to reuse binary packages(if available) to satisfy the dependencies for the ebuild(source) package, speeding up the installation. - You can use the --ebuild option even if you don't want to install any ebuild(source) packages; It will fall back to binary packages only. - - The --oneshot option will install the packages as described above, however it will not add them to the 'world' set, which means they will not be marked as - explicitly installed. As a result, they will be treated as orphans and they will be uninstalled with 'sisyphus autoremove' if no other package needs them as - a depencency, unless they are explicitly added to the 'world' set using 'emerge --noreplace pkgname'. + False, "--ebuild", "-e", help='Install ebuild(source) package if binary package is not found (slower)'), + oneshot: bool = typer.Option(False, "--oneshot", "-1", help='Do not mark the package as explicitly installed')): + """ + Install binary and/or ebuild(source) packages.\n + Binary packages are default, however the --ebuild option can be used to install ebuild(source) packages.\n + The --ebuild option will be automatically suggested if a binary package is not found, but an ebuild(source) package is found.\n + The --ebuild option will fall back to binary packages if installation from ebuild(source) package is not required. (Can be used at all times, *SAFELY*).\n + The --ebuild option will prefer to use binary packages (if available) to satisfy dependencies for the ebuild(source) package, speeding up the installation.\n + The --oneshot option follows the above rules, however it will not mark the package as explicitly installed. (In Gentoo Linux terms: not added to world set).\n + The --ebuild and the --oneshot options can be used both independently of each other and/or combined with each other.\n + \n + * Examples:\n + sisyphus install firefox\n + sisyphus install pidgin --ebuild\n + sisyphus install xonotic -e\n + sisyphus install filezilla --oneshot\n + sisyphus install thunderbird -1\n + sisyphus install falkon -e -1\n + sisyphus install opera --ebuild --oneshot\n + sisyphus install vivaldi --oneshot --ebuild\n """ if ebuild: sisyphus.install.start(pkgname, ebuild=True, @@ -148,36 +131,20 @@ def install(pkgname: List[str], @app.command("uninstall") -def uninstall(pkgname: List[str], force: bool = typer.Option(False, "--force", "-f")): - """Uninstall packages *SAFELY* by checking for reverse dependencies. - If reverse dependencies exist, the package(s) will NOT be uninstalled to prevent the possible breakage of the system. - If you really want to uninstall the package, make sure you uninstall all reverse dependencies as well. - This will not allways be possible, as the reverse dependency chain may be way to long and require you to uninstall critical system packages. - - * Examples: - - sisyphus uninstall firefox - - will succeed, nothing depends on it - - sisyphus uninstall pulseaudio - - will fail, many packages depend on it - - With --force option, packages are uninstalled *UNSAFELY* by ignoring reverse dependencies. - This may break your system if you uninstall critical packages. - It will try the best it can to preserve the libraries required by other packages to prevent such a breakage. - Upgrading the system may pull the packages back in, to fix the reverse dependency chain. - - * Examples : - - sisyphus uninstall pulseaudio --force - - will succeed, but you may no longer have audio - - sisyphus uninstall openrc --force - - will succeed, but the system will be broken +def uninstall(pkgname: List[str], force: bool = typer.Option(False, "--force", "-f", help='Ignore the reverse dependencies and force uninstall the package (DANGEROUS)')): + """ + Uninstall packages *SAFELY* by checking for reverse dependencies.\n + If there are any reverse dependencies, the package or packages will NOT be uninstalled to prevent the system from breaking.\n + If you are serious about uninstalling the package, it is recommended you uninstall all the reverse dependencies of it as well.\n + This will not always be possible because the reverse dependency tree may be too long and you may need to uninstall important system packages.\n + DANGEROUS : The --force option will ignore the reverse dependencies and uninstall the package *UNSAFELY*, without safeguards.\n + WARNING : The --force option will break your system if you uninstall important system packages (bootloader, kernel, init).\n + \n + * Examples:\n + sisyphus uninstall firefox # this will succeed, no package depends on firefox\n + sisyphus uninstall pulseaudio # this will fail, many packages depend on pulseaudio\n + sisyphus uninstall pulseaudio --force # this will succeed, but the sound may no longer work\n + sisyphus uninstall openrc -f # this will succeed, but the system will no longer boot\n """ if force: sisyphus.uninstall.start( @@ -189,17 +156,27 @@ def uninstall(pkgname: List[str], force: bool = typer.Option(False, "--force", " @app.command("autoremove") def autoremove(): - """Uninstall packages that are no longer needed. - When you uninstall a package without it's reverse dependencies, those dependencies will become orphans if nothing else requires them. - In addition, a package may no longer depend on another one, so that other package becomes orphan as well if nothing else requires it. - Use this option to check the whole dependency chain for such packages, and uninstall them. + """ + Uninstall packages which become orphans and which are no longer needed.\n + Uninstalling a package will usually leave it's dependencies behind. Those dependencies become orphans if no other package requires them.\n + A package may also gain extra dependencies, or loose some dependencies. The lost dependencies become orphans if no other package requires them.\n + In both cases, the orphan packages are no longer needed and can be safely removed.\n + Use this option to check the whole dependency tree for orphan packages, and remove them.\n + \n + * Examples:\n + sisyphus autoremove\n """ sisyphus.autoremove.start(gfx_ui=False) @app.command("autoclean") def autoclean(): - """Clean the binary package cache and the source tarball cache""" + """ + Clean the binary package cache and the source tarball cache.\n + \n + * Examples:\n + sisyphus autoclean\n + """ if sisyphus.checkenv.root(): sisyphus.purgeenv.cache() else: @@ -208,7 +185,12 @@ def autoclean(): @app.command("update") def update(): - """Update the Portage tree, the Redcore Overlay(s), Portage configs and Sisyphus's package database.""" + """ + Update the source trees, package configs (USE flags, keywords, masks, etc) and the binary package database.\n + \n + * Examples:\n + sisyphus update\n + """ if sisyphus.checkenv.root(): sisyphus.update.start(gfx_ui=False) else: @@ -217,24 +199,18 @@ def update(): @app.command("upgrade") def upgrade( - ebuild: bool = typer.Option(False, "--ebuild", "-e", help='Upgrade all packages, including ebuild (source) packages previously installed (slower)')): - """Upgrade the system using binary and/or ebuild (source) packages. - By default, only binary packages will be upgraded. - However, if you installed any ebuild(source) packages with the '--ebuild' option, it would make sense to upgrade them too. - Use the --ebuild option to upgrade **EVERYTHING**, binary and/or ebuild(source) packages. - - * Examples: - - sisyphus upgrade - - will upgrade the system using binary packages; if any ebuild(source) package upgrade is detected, it will stop and suggest the --ebuild option - - sisyphus upgrade --ebuild - - will upgrade the system using both binary and/or ebuild(source) packages - - The --ebuild option will preffer to reuse binary packages(if available) to satisfy the dependencies for the ebuild(source) packages, speeding up the upgrade. - You can use the --ebuild option even if you don't have any ebuild(source) packages installed; It will fall back to binary packages only. + ebuild: bool = typer.Option(False, "--ebuild", "-e", help='Upgrade all packages, including ebuild(source) packages (slower)')): + """ + Upgrade the system using binary and/or ebuild(source) packages.\n + Binary packages are default, however the --ebuild option can be used to upgrade the ebuild(source) packages as well, alongside the binary packages.\n + The --ebuild option will be automatically suggested if the ebuild(source) packages need to be upgraded as well, alongside the binary packages.\n + The --ebuild option will fall back to binary packages if the ebuild(source) packages don't require any upgrade. (Can be used at all times, *SAFELY*).\n + The --ebuild option will prefer to use binary packages (if available) to satisfy dependencies for the ebuild(source) packages, speeding up the upgrade.\n + \n + * Examples:\n + sisyphus upgrade\n + sisyphus upgrade --ebuild\n + sisyphus upgrade -e\n """ if ebuild: sisyphus.upgrade.start(ebuild=True, gfx_ui=False) @@ -244,19 +220,27 @@ def upgrade( @app.command("spmsync") def spmsync(): - """Sync Sisyphus's package database with Portage's package database. - When you install something with Portage directly (emerge), Sisyphus is not aware of that package, and it doesn't track it in it's database. - Use this command to synchronize Sisyphus's package database with Portage's package database. + """ + Sync Sisyphus's package database with Portage's package database.\n + Sisyphus does not track packages installed directly via Portage in it's package database.\n + Use this command to synchronize Sisyphus's package database with Portage's package database.\n + \n + * Examples:\n + sisyphus spmsync\n """ sisyphus.syncspm.start() @app.command("rescue") def rescue(): - """Resurrect Sisyphus's package database if lost or corrupted. - If for some reason Sisyphus's package database is lost or corrupted, it can be resurrected using Portage's package database. - If Portage's package database is corrupted (in this case you're screwed anyway :D), only a partial resurrection will be possible. - If Portage's package database is intact, full resurrection will be possible. + """ + Resurrect Sisyphus's package database if lost or corrupted.\n + If for some reason Sisyphus's package database is lost or corrupted, it can be resurrected using Portage's package database.\n + If Portage's package database is corrupted (in this case you're screwed anyway :D), only a partial resurrection will be possible.\n + If Portage's package database is intact, full resurrection will be possible.\n + \n + * Examples:\n + sisyphus rescue\n """ sisyphus.recoverdb.start() @@ -274,59 +258,69 @@ class Remote(str, Enum): @app.command("branch") def branch(branch: Branch = typer.Argument(...), remote: Remote = typer.Option(Remote.gitlab, "--remote", "-r")): - """Pull the selected branch of the Portage tree, Redcore overlay and Portage configs. - The remote can be selected by using the --remote option. - - 'BRANCH' can be one of the following : master, next - - 'REMOTE' can be one of the following : github, gitlab, pagure (default is gitlab) - - * Examples: - - branch next --remote=github # pull the branch 'next' from github.com - - branch master --remote=gitlab # pull the branch 'master' from gitlab.com - - branch next --remote=pagure # pull the branch 'next' from pagure.io - - !!! WARNING !!! - - Once you changed the branch, you must pair it with the correct binhost (binary repository). - - Branch 'master' must be paired with the stable binhost (binary repository) (odd numbers in 'sisyphus mirror list'). - - * Examples: - - sisyphus mirror set 1 - - sisyphus mirror set 5 - - Branch 'next' must be paired with the testing binhost (binary repository) (even numbers in 'sisyphus mirror list'). - - * Examples: - - sisyphus mirror set 2 - - sisyphus mirror set 8 + """ + Switch between the branches of Redcore Linux : 'master' (stable) or 'next' (testing), default branch is 'master' (stable)\n + Reconfigure the source trees, package configs (USE flags, keywords, masks, etc) and the binhost (binary repository)\n + Selection of a remote is optional (default is gitlab), but it can be accomplished by using the --remote option.\n + 'BRANCH' can be one of the following : master, next\n + 'REMOTE' can be one of the following : github, gitlab, pagure (default is gitlab)\n + \n + * Examples:\n + sisyphus branch master # switch to branch 'master', use default remote (gitlab)\n + sisyphus branch next # switch to branch 'next', use default remote (gitlab)\n + sisyphus branch master --remote=github # switch to branch 'master', use github remote\n + sisyphus branch next --remote=pagure # switch to branch 'next', use pagure remote\n + \n + Sisyphus will automatically pair the selected branch with the correct binhost (binary repository).\n + However, since no geolocation is ever used, it may select one which is geographically far from you.\n + If that is inconvenient, you can manually select a binhost (binary repository) closer to your location,\n + \n + !!! WARNING !!!\n + \n + Branch 'master' must be paired with the stable binhost (binary repository) (odd numbers in 'sisyphus mirror list').\n + * Examples:\n + sisyphus mirror set 1\n + sisyphus mirror set 5\n + \n + Branch 'next' must be paired with the testing binhost (binary repository) (even numbers in 'sisyphus mirror list').\n + * Examples:\n + sisyphus mirror set 2\n + sisyphus mirror set 8\n """ sisyphus.setbranch.start(branch.value, remote.value) @app.command("sysinfo") def sysinfo(): - """Display information about installed core packages and portage configuration.""" + """ + Display information about installed core packages and portage configuration.\n + \n + * Examples:\n + sisyphus sysinfo\n + """ sisyphus.sysinfo.show() @mirrorSetup.command("list") def mirrorlist(): - """List available binary package repository mirrors (the active one is marked with *).""" + """ + List available binary package repository mirrors (the active one is marked with *).\n + \n + * Examples:\n + sisyphus mirror list\n + """ sisyphus.mirrors.printList() @mirrorSetup.command("set") def mirrorset(index: int): - """Change the binary package repository to the selected mirror.""" + """ + Change the binary package repository to the selected mirror.\n + \n + * Examples:\n + sisyphus mirror set 2\n + sisyphus mirror set 5\n + """ sisyphus.mirrors.setActive(index) -- cgit v1.2.3