diff --git a/docs/cog_guides/downloader.rst b/docs/cog_guides/downloader.rst new file mode 100644 index 000000000..cd8169e41 --- /dev/null +++ b/docs/cog_guides/downloader.rst @@ -0,0 +1,537 @@ +.. _downloader: + +========== +Downloader +========== + +This is the cog guide for the downloader cog. You will +find detailed docs about usage and commands. + +``[p]`` is considered as your prefix. + +.. note:: To use this cog, load it by typing this:: + + [p]load downloader + +.. _downloader-usage: + +----- +Usage +----- + +Install community cogs made by Cog Creators. + +Community cogs, also called third party cogs, are not included +in the default Red install. + +Community cogs come in repositories. Repos are a group of cogs +you can install. You always need to add the creator's repository +using the ``[p]repo`` command before you can install one or more +cogs from the creator. + + +.. _downloader-commands: + +-------- +Commands +-------- + +.. _downloader-command-cog: + +^^^ +cog +^^^ + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]cog + +**Description** + +Base command for cog installation management commands. + +.. _downloader-command-cog-checkforupdates: + +""""""""""""""""""" +cog checkforupdates +""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]cog checkforupdates + +**Description** + +Check for available cog updates (including pinned cogs). + +This command doesn't update cogs, it only checks for updates. +Use ``[p]cog update`` to update cogs. + +.. _downloader-command-cog-info: + +"""""""" +cog info +"""""""" + +**Syntax** + +.. code-block:: none + + [p]cog info + +**Description** + +List information about a single cog. + +Example: + - ``[p]cog info 26-Cogs defender`` + +**Arguments** + +- ```` The repo to get cog info from. +- ```` The cog to get info on. + +.. _downloader-command-cog-install: + +""""""""""" +cog install +""""""""""" + +**Syntax** + +.. code-block:: none + + [p]cog install + +**Description** + +Install a cog from the given repo. + +Examples: + - ``[p]cog install 26-Cogs defender`` + - ``[p]cog install Laggrons-Dumb-Cogs say roleinvite`` + +**Arguments** + +- ```` The name of the repo to install cogs from. +- ```` The cog or cogs to install. + +.. _downloader-command-cog-installversion: + +"""""""""""""""""" +cog installversion +"""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]cog installversion + +**Description** + +Install a cog from the specified revision of given repo. + +Revisions are "commit ids" that point to the point in the code when a specific change was made. +The latest revision can be found in the URL bar for any GitHub repo by `pressing "y" on that repo `_. + +Older revisions can be found in the URL bar by `viewing the commit history of any repo `_ + +Example: + - ``[p]cog installversion Broken-Repo e798cc268e199612b1316a3d1f193da0770c7016 cog_name`` + +**Arguments** + +- ```` The name of the repo to install cogs from. +- ```` The revision to install from. +- ```` The cog or cogs to install. + +.. _downloader-command-cog-list: + +"""""""" +cog list +"""""""" + +**Syntax** + +.. code-block:: none + + [p]cog list + +**Description** + +List all available cogs from a single repo. + +Example: + - ``[p]cog list 26-Cogs`` + +**Arguments** + +- ```` The repo to list cogs from. + +.. _downloader-command-cog-listpinned: + +"""""""""""""" +cog listpinned +"""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]cog listpinned + +**Description** + +List currently pinned cogs. + +.. _downloader-command-cog-pin: + +""""""" +cog pin +""""""" + +**Syntax** + +.. code-block:: none + + [p]cog pin + +**Description** + +Pin cogs - this will lock cogs on their current version. + +Examples: + - ``[p]cog pin defender`` + - ``[p]cog pin outdated_cog1 outdated_cog2`` + +**Arguments** + +- ```` The cog or cogs to pin. Must already be installed. + +.. _downloader-command-cog-uninstall: + +""""""""""""" +cog uninstall +""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]cog uninstall + +**Description** + +Uninstall cogs. + +You may only uninstall cogs which were previously installed +by Downloader. + +Examples: + - ``[p]cog uninstall 26-Cogs defender`` + - ``[p]cog uninstall Laggrons-Dumb-Cogs say roleinvite`` + +**Arguments** + +- ```` The cog or cogs to uninstall. + +.. _downloader-command-cog-unpin: + +""""""""" +cog unpin +""""""""" + +**Syntax** + +.. code-block:: none + + [p]cog unpin + +**Description** + +Unpin cogs - this will remove the update lock from those cogs. + +Examples: + - ``[p]cog unpin defender`` + - ``[p]cog unpin updated_cog1 updated_cog2`` + +**Arguments** + +- ```` The cog or cogs to unpin. Must already be installed and pinned. + +.. _downloader-command-cog-update: + +"""""""""" +cog update +"""""""""" + +**Syntax** + +.. code-block:: none + + [p]cog update [cogs...] + +**Description** + +Update all cogs, or ones of your choosing. + +Examples: + - ``[p]cog update`` + - ``[p]cog update defender`` + +**Arguments** + +- ``[cogs...]`` The cog or cogs to update. If omitted, all cogs are updated. + +.. _downloader-command-cog-updateallfromrepos: + +"""""""""""""""""""""" +cog updateallfromrepos +"""""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]cog updateallfromrepos + +**Description** + +Update all cogs from repos of your choosing. + +Examples: + - ``[p]cog updateallfromrepos 26-Cogs`` + - ``[p]cog updateallfromrepos Laggrons-Dumb-Cogs 26-Cogs`` + +**Arguments** + +- ```` The repo or repos to update all cogs from. + +.. _downloader-command-cog-updatetoversion: + +""""""""""""""""""" +cog updatetoversion +""""""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]cog updatetoversion [cogs] + +**Description** + +Update all cogs, or ones of your choosing to chosen revision of one repo. + +Note that update doesn't mean downgrade and therefore ``revision`` +has to be newer than the version that cog currently has installed. If you want to +downgrade the cog, uninstall and install it again. + +See ``[p]cog installversion`` for an explanation of ``revision``. + +Example: + - ``[p]cog updatetoversion Broken-Repo e798cc268e199612b1316a3d1f193da0770c7016 cog_name`` + +**Arguments** + +- ```` The repo or repos to update all cogs from. +- ```` The revision to update to. +- ``[cogs]`` The cog or cogs to update. + +.. _downloader-command-findcog: + +^^^^^^^ +findcog +^^^^^^^ + +**Syntax** + +.. code-block:: none + + [p]findcog + +**Description** + +Find which cog a command comes from. + +This will only work with loaded cogs. + +Example: + - ``[p]findcog ping`` + +**Arguments** + +- ```` The command to search for. + +.. _downloader-command-pipinstall: + +^^^^^^^^^^ +pipinstall +^^^^^^^^^^ + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]pipinstall [deps...] + +**Description** + +Install a group of dependencies using pip. + +Examples: + - ``[p]pipinstall bs4`` + - ``[p]pipinstall py-cpuinfo psutil`` + +Improper usage of this command can break your bot, be careful. + +**Arguments** + +- ``[deps...]`` The package or packages you wish to install. + +.. _downloader-command-repo: + +^^^^ +repo +^^^^ + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]repo + +**Description** + +Base command for repository management. + +.. _downloader-command-repo-add: + +"""""""" +repo add +"""""""" + +**Syntax** + +.. code-block:: none + + [p]repo add [branch] + +**Description** + +Add a new repo. + +Examples: + - ``[p]repo add 26-Cogs https://github.com/Twentysix26/x26-Cogs`` + - ``[p]repo add Laggrons-Dumb-Cogs https://github.com/retke/Laggrons-Dumb-Cogs v3`` + +Repo names can only contain characters A-z, numbers, underscores, and hyphens. +The branch will be the default branch if not specified. + +**Arguments** + +- ```` The name given to the repo. +- ```` URL to the cog branch. Usually GitHub or GitLab. +- ``[branch]`` Optional branch to install cogs from. + +.. _downloader-command-repo-delete: + +""""""""""" +repo delete +""""""""""" + +**Syntax** + +.. code-block:: none + + [p]repo delete + +.. tip:: Aliases: ``repo remove``, ``repo del`` + +**Description** + +Remove a repo and its files. + +Example: + - ``[p]repo delete 26-Cogs`` + +**Arguments** + +- ```` The name of an already added repo + +.. _downloader-command-repo-info: + +""""""""" +repo info +""""""""" + +**Syntax** + +.. code-block:: none + + [p]repo info + +**Description** + +Show information about a repo. + +Example: + - ``[p]repo info 26-Cogs`` + +**Arguments** + +- ```` The name of the repo to show info about. + +.. _downloader-command-repo-list: + +""""""""" +repo list +""""""""" + +**Syntax** + +.. code-block:: none + + [p]repo list + +**Description** + +List all installed repos. + +.. _downloader-command-repo-update: + +""""""""""" +repo update +""""""""""" + +**Syntax** + +.. code-block:: none + + [p]repo update [repos...] + +**Description** + +Update all repos, or ones of your choosing. + +This will *not* update the cogs installed from those repos. + +Examples: + - ``[p]repo update`` + - ``[p]repo update 26-Cogs`` + - ``[p]repo update 26-Cogs Laggrons-Dumb-Cogs`` + +**Arguments** + +- ``[repos...]`` The name or names of repos to update. If omitted, all repos are updated. diff --git a/docs/index.rst b/docs/index.rst index 9b9683fd8..1e7ba21db 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -38,6 +38,7 @@ Welcome to Red - Discord Bot's documentation! cog_guides/cleanup cog_guides/cog_manager_ui cog_guides/customcommands + cog_guides/downloader red_core_data_statement .. toctree:: diff --git a/redbot/cogs/downloader/downloader.py b/redbot/cogs/downloader/downloader.py index 4ac0cd40a..eb01aa9cf 100644 --- a/redbot/cogs/downloader/downloader.py +++ b/redbot/cogs/downloader/downloader.py @@ -481,7 +481,19 @@ class Downloader(commands.Cog): @commands.command() @checks.is_owner() async def pipinstall(self, ctx: commands.Context, *deps: str) -> None: - """Install a group of dependencies using pip.""" + """ + Install a group of dependencies using pip. + + Examples: + - `[p]pipinstall bs4` + - `[p]pipinstall py-cpuinfo psutil` + + Improper usage of this command can break your bot, be careful. + + **Arguments** + + - `[deps...]` The package or packages you wish to install. + """ if not deps: await ctx.send_help() return @@ -502,7 +514,7 @@ class Downloader(commands.Cog): @commands.group() @checks.is_owner() async def repo(self, ctx: commands.Context) -> None: - """Repo management commands.""" + """Base command for repository management.""" pass @repo.command(name="add") @@ -511,8 +523,18 @@ class Downloader(commands.Cog): ) -> None: """Add a new repo. + Examples: + - `[p]repo add 26-Cogs https://github.com/Twentysix26/x26-Cogs` + - `[p]repo add Laggrons-Dumb-Cogs https://github.com/retke/Laggrons-Dumb-Cogs v3` + Repo names can only contain characters A-z, numbers, underscores, and hyphens. The branch will be the default branch if not specified. + + **Arguments** + + - `` The name given to the repo. + - `` URL to the cog branch. Usually GitHub or GitLab. + - `[branch]` Optional branch to install cogs from. """ agreed = await do_install_agreement(ctx) if not agreed: @@ -562,7 +584,16 @@ class Downloader(commands.Cog): @repo.command(name="delete", aliases=["remove", "del"], usage="") async def _repo_del(self, ctx: commands.Context, repo: Repo) -> None: - """Remove a repo and its files.""" + """ + Remove a repo and its files. + + Example: + - `[p]repo delete 26-Cogs` + + **Arguments** + + - `` The name of an already added repo + """ await self._repo_manager.delete_repo(repo.name) await ctx.send( @@ -583,7 +614,15 @@ class Downloader(commands.Cog): @repo.command(name="info", usage="") async def _repo_info(self, ctx: commands.Context, repo: Repo) -> None: - """Show information about a repo.""" + """Show information about a repo. + + Example: + - `[p]repo info 26-Cogs` + + **Arguments** + + - `` The name of the repo to show info about. + """ made_by = ", ".join(repo.author) or _("Missing from info.json") information = _("Repo url: {repo_url}\n").format(repo_url=repo.clean_url) @@ -601,7 +640,19 @@ class Downloader(commands.Cog): @repo.command(name="update") async def _repo_update(self, ctx: commands.Context, *repos: Repo) -> None: - """Update all repos, or ones of your choosing.""" + """Update all repos, or ones of your choosing. + + This will *not* update the cogs installed from those repos. + + Examples: + - `[p]repo update` + - `[p]repo update 26-Cogs` + - `[p]repo update 26-Cogs Laggrons-Dumb-Cogs` + + **Arguments** + + - `[repos...]` The name or names of repos to update. If omitted, all repos are updated. + """ async with ctx.typing(): updated: Set[str] @@ -627,15 +678,17 @@ class Downloader(commands.Cog): @commands.group() @checks.is_owner() async def cog(self, ctx: commands.Context) -> None: - """Cog installation management commands.""" + """Base command for cog installation management commands.""" pass @cog.command(name="reinstallreqs", hidden=True) async def _cog_reinstallreqs(self, ctx: commands.Context) -> None: """ + This command should not be used unless Red specifically asks for it. + This command will reinstall cog requirements and shared libraries for all installed cogs. - Red might ask user to use this when it clears contents of lib folder + Red might ask the owner to use this when it clears contents of the lib folder because of change in minor version of Python. """ async with ctx.typing(): @@ -686,14 +739,39 @@ class Downloader(commands.Cog): @cog.command(name="install", usage=" ") async def _cog_install(self, ctx: commands.Context, repo: Repo, *cog_names: str) -> None: - """Install a cog from the given repo.""" + """Install a cog from the given repo. + + Examples: + - `[p]cog install 26-Cogs defender` + - `[p]cog install Laggrons-Dumb-Cogs say roleinvite` + + **Arguments** + + - `` The name of the repo to install cogs from. + - `` The cog or cogs to install. + """ await self._cog_installrev(ctx, repo, None, cog_names) @cog.command(name="installversion", usage=" ") async def _cog_installversion( self, ctx: commands.Context, repo: Repo, rev: str, *cog_names: str ) -> None: - """Install a cog from the specified revision of given repo.""" + """Install a cog from the specified revision of given repo. + + Revisions are "commit ids" that point to the point in the code when a specific change was made. + The latest revision can be found in the URL bar for any GitHub repo by [pressing "y" on that repo](https://docs.github.com/en/free-pro-team@latest/github/managing-files-in-a-repository/getting-permanent-links-to-files#press-y-to-permalink-to-a-file-in-a-specific-commit). + + Older revisions can be found in the URL bar by [viewing the commit history of any repo](https://cdn.discordapp.com/attachments/133251234164375552/775760247787749406/unknown.png) + + Example: + - `[p]cog installversion Broken-Repo e798cc268e199612b1316a3d1f193da0770c7016 cog_name` + + **Arguments** + + - `` The name of the repo to install cogs from. + - `` The revision to install from. + - `` The cog or cogs to install. + """ await self._cog_installrev(ctx, repo, rev, cog_names) async def _cog_installrev( @@ -798,6 +876,14 @@ class Downloader(commands.Cog): You may only uninstall cogs which were previously installed by Downloader. + + Examples: + - `[p]cog uninstall 26-Cogs defender` + - `[p]cog uninstall Laggrons-Dumb-Cogs say roleinvite` + + **Arguments** + + - `` The cog or cogs to uninstall. """ if not cogs: await ctx.send_help() @@ -839,7 +925,16 @@ class Downloader(commands.Cog): @cog.command(name="pin", usage="") async def _cog_pin(self, ctx: commands.Context, *cogs: InstalledCog) -> None: - """Pin cogs - this will lock cogs on their current version.""" + """Pin cogs - this will lock cogs on their current version. + + Examples: + - `[p]cog pin defender` + - `[p]cog pin outdated_cog1 outdated_cog2` + + **Arguments** + + - `` The cog or cogs to pin. Must already be installed. + """ if not cogs: await ctx.send_help() return @@ -862,7 +957,15 @@ class Downloader(commands.Cog): @cog.command(name="unpin", usage="") async def _cog_unpin(self, ctx: commands.Context, *cogs: InstalledCog) -> None: - """Unpin cogs - this will remove update lock from cogs.""" + """Unpin cogs - this will remove the update lock from those cogs. + + Examples: + - `[p]cog unpin defender` + - `[p]cog unpin updated_cog1 updated_cog2` + + **Arguments** + + - `` The cog or cogs to unpin. Must already be installed and pinned.""" if not cogs: await ctx.send_help() return @@ -947,12 +1050,30 @@ class Downloader(commands.Cog): @cog.command(name="update") async def _cog_update(self, ctx: commands.Context, *cogs: InstalledCog) -> None: - """Update all cogs, or ones of your choosing.""" + """Update all cogs, or ones of your choosing. + + Examples: + - `[p]cog update` + - `[p]cog update defender` + + **Arguments** + + - `[cogs...]` The cog or cogs to update. If omitted, all cogs are updated. + """ await self._cog_update_logic(ctx, cogs=cogs) @cog.command(name="updateallfromrepos", usage="") async def _cog_updateallfromrepos(self, ctx: commands.Context, *repos: Repo) -> None: - """Update all cogs from repos of your choosing.""" + """Update all cogs from repos of your choosing. + + Examples: + - `[p]cog updateallfromrepos 26-Cogs` + - `[p]cog updateallfromrepos Laggrons-Dumb-Cogs 26-Cogs` + + **Arguments** + + - `` The repo or repos to update all cogs from. + """ if not repos: await ctx.send_help() return @@ -964,9 +1085,20 @@ class Downloader(commands.Cog): ) -> None: """Update all cogs, or ones of your choosing to chosen revision of one repo. - Note that update doesn't mean downgrade and therefore revision - has to be newer than the one that cog currently has. If you want to + Note that update doesn't mean downgrade and therefore `revision` + has to be newer than the version that cog currently has installed. If you want to downgrade the cog, uninstall and install it again. + + See `[p]cog installversion` for an explanation of `revision`. + + Example: + - `[p]cog updatetoversion Broken-Repo e798cc268e199612b1316a3d1f193da0770c7016 cog_name` + + **Arguments** + + - `` The repo or repos to update all cogs from. + - `` The revision to update to. + - `[cogs]` The cog or cogs to update. """ await self._cog_update_logic(ctx, repo=repo, rev=rev, cogs=cogs) @@ -1089,7 +1221,15 @@ class Downloader(commands.Cog): @cog.command(name="list", usage="") async def _cog_list(self, ctx: commands.Context, repo: Repo) -> None: - """List all available cogs from a single repo.""" + """List all available cogs from a single repo. + + Example: + - `[p]cog list 26-Cogs` + + **Arguments** + + - `` The repo to list cogs from. + """ installed = await self.installed_cogs() installed_str = "" if installed: @@ -1113,7 +1253,16 @@ class Downloader(commands.Cog): @cog.command(name="info", usage=" ") async def _cog_info(self, ctx: commands.Context, repo: Repo, cog_name: str) -> None: - """List information about a single cog.""" + """List information about a single cog. + + Example: + - `[p]cog info 26-Cogs defender` + + **Arguments** + + - `` The repo to get cog info from. + - `` The cog to get info on. + """ cog = discord.utils.get(repo.available_cogs, name=cog_name) if cog is None: await ctx.send( @@ -1424,6 +1573,13 @@ class Downloader(commands.Cog): """Find which cog a command comes from. This will only work with loaded cogs. + + Example: + - `[p]findcog ping` + + **Arguments** + + - `` The command to search for. """ command = ctx.bot.all_commands.get(command_name)