[Docs] Downloader cog guide (#4511)

* 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

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 <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.

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

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**
+
+        - `<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
+        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
+        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)