CopyBot/Red-DiscordBot
1
0
Fork 0
mirror of https://github.com/Cog-Creators/Red-DiscordBot.git synced 2025-11-06 03:08:55 -05:00
Code Issues Packages Projects Releases Wiki Activity

[Docs] Downloader cog guide (#4511)

Browse Source 
* Downloader cog guide initial commit

* Updated cogguide to prepare description on cog as well.

* Lots of docstring updates

* Even more docstrings

* Fix docstring and generate docs

* Switch to alphabetical

* Aliases are `in ticks and fully qualified`

* Fix grammer, arguments, and explain revision.

* Regenerated docs

* Avoid ticks in links

* New URL logic

* Additional grammar fixes

* Regenerate docs
This commit is contained in:
bobloy 2020-11-20 20:18:04 -05:00 committed by GitHub
parent bc8f2311d9
commit c7fd561cd5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 711 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

537
docs/cog_guides/downloader.rst Normal file
View File

@ -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 <repo_name> <cog_name>
**Description**
List information about a single cog.
Example:
- ``[p]cog info 26-Cogs defender``
**Arguments**
- ``<repo_name>`` The repo to get cog info from.
- ``<cog_name>`` The cog to get info on.
.. _downloader-command-cog-install:
"""""""""""
cog install
"""""""""""
**Syntax**
.. code-block:: none
[p]cog install <repo_name> <cogs>
**Description**
Install a cog from the given repo.
Examples:
- ``[p]cog install 26-Cogs defender``
- ``[p]cog install Laggrons-Dumb-Cogs say roleinvite``
**Arguments**
- ``<repo_name>`` The name of the repo to install cogs from.
- ``<cogs>`` The cog or cogs to install.
.. _downloader-command-cog-installversion:
""""""""""""""""""
cog installversion
""""""""""""""""""
**Syntax**
.. code-block:: none
[p]cog installversion <repo_name> <revision> <cogs>
**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 <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**
- ``<repo_name>`` The name of the repo to install cogs from.
- ``<revision>`` The revision to install from.
- ``<cogs>`` The cog or cogs to install.
.. _downloader-command-cog-list:
""""""""
cog list
""""""""
**Syntax**
.. code-block:: none
[p]cog list <repo_name>
**Description**
List all available cogs from a single repo.
Example:
- ``[p]cog list 26-Cogs``
**Arguments**
- ``<repo_name>`` 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 <cogs>
**Description**
Pin cogs - this will lock cogs on their current version.
Examples:
- ``[p]cog pin defender``
- ``[p]cog pin outdated_cog1 outdated_cog2``
**Arguments**
- ``<cogs>`` The cog or cogs to pin. Must already be installed.
.. _downloader-command-cog-uninstall:
"""""""""""""
cog uninstall
"""""""""""""
**Syntax**
.. code-block:: none
[p]cog uninstall <cogs>
**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**
- ``<cogs>`` The cog or cogs to uninstall.
.. _downloader-command-cog-unpin:
"""""""""
cog unpin
"""""""""
**Syntax**
.. code-block:: none
[p]cog unpin <cogs>
**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**
- ``<cogs>`` 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 <repos>
**Description**
Update all cogs from repos of your choosing.
Examples:
- ``[p]cog updateallfromrepos 26-Cogs``
- ``[p]cog updateallfromrepos Laggrons-Dumb-Cogs 26-Cogs``
**Arguments**
- ``<repos>`` The repo or repos to update all cogs from.
.. _downloader-command-cog-updatetoversion:
"""""""""""""""""""
cog updatetoversion
"""""""""""""""""""
**Syntax**
.. code-block:: none
[p]cog updatetoversion <repo_name> <revision> [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**
- ``<repo_name>`` The repo or repos to update all cogs from.
- ``<revision>`` The revision to update to.
- ``[cogs]`` The cog or cogs to update.
.. _downloader-command-findcog:
^^^^^^^
findcog
^^^^^^^
**Syntax**
.. code-block:: none
[p]findcog <command_name>
**Description**
Find which cog a command comes from.
This will only work with loaded cogs.
Example:
- ``[p]findcog ping``
**Arguments**
- ``<command_name>`` 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 <name> <repo_url> [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**
- ``<name>`` The name given to the repo.
- ``<repo_url>`` 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 <repo_name>
.. tip:: Aliases: ``repo remove``, ``repo del``
**Description**
Remove a repo and its files.
Example:
- ``[p]repo delete 26-Cogs``
**Arguments**
- ``<repo_name>`` The name of an already added repo
.. _downloader-command-repo-info:
"""""""""
repo info
"""""""""
**Syntax**
.. code-block:: none
[p]repo info <repo_name>
**Description**
Show information about a repo.
Example:
- ``[p]repo info 26-Cogs``
**Arguments**
- ``<repo_name>`` 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.

1
docs/index.rst
View File

@ -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::

190
redbot/cogs/downloader/downloader.py
View File

@ -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**
- `<name>` The name given to the repo.
- `<repo_url>` 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="<repo_name>")
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**
- `<repo_name>` 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="<repo_name>")
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**
- `<repo_name>` 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="<repo_name> <cogs>")
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**
- `<repo_name>` The name of the repo to install cogs from.
- `<cogs>` The cog or cogs to install.
"""
await self._cog_installrev(ctx, repo, None, cog_names)
@cog.command(name="installversion", usage="<repo_name> <revision> <cogs>")
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**
- `<repo_name>` The name of the repo to install cogs from.
- `<revision>` The revision to install from.
- `<cogs>` 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**
- `<cogs>` 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="<cogs>")
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**
- `<cogs>` 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="<cogs>")
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**
- `<cogs>` 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="<repos>")
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**
- `<repos>` 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**
- `<repo_name>` The repo or repos to update all cogs from.
- `<revision>` 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="<repo_name>")
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**
- `<repo_name>` 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="<repo_name> <cog_name>")
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**
- `<repo_name>` The repo to get cog info from.
- `<cog_name>` 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**
- `<command_name>` The command to search for.
"""
command = ctx.bot.all_commands.get(command_name)