From debed501b2f446140fb30b98b3f1324ad3bf8fde Mon Sep 17 00:00:00 2001 From: jack1142 <6032823+jack1142@users.noreply.github.com> Date: Thu, 2 Jan 2020 14:28:50 +0100 Subject: [PATCH] [Docs] Remove API Reference for downloader, add page about publishing cogs (#3234) * docs: add info about publishing cogs, remove downloader reference Co-authored-by: Redjumpman * chore(changelog): add towncrier entries * docs: fix broken reference in 3.1.0 changelog Co-authored-by: Redjumpman --- changelog.d/3234.docs.rst | 1 + changelog.d/downloader/3234.docs.rst | 1 + docs/changelog_3_1_0.rst | 2 +- docs/cog_downloader.rst | 9 --- docs/guide_cog_creation.rst | 12 ++- docs/guide_migration.rst | 6 +- ..._downloader.rst => guide_publish_cogs.rst} | 81 ++++++++----------- docs/index.rst | 3 +- 8 files changed, 48 insertions(+), 67 deletions(-) create mode 100644 changelog.d/3234.docs.rst create mode 100644 changelog.d/downloader/3234.docs.rst delete mode 100644 docs/cog_downloader.rst rename docs/{framework_downloader.rst => guide_publish_cogs.rst} (64%) diff --git a/changelog.d/3234.docs.rst b/changelog.d/3234.docs.rst new file mode 100644 index 000000000..33e926134 --- /dev/null +++ b/changelog.d/3234.docs.rst @@ -0,0 +1 @@ +Added "Publishing cogs for V3" document explaining how to make user's cogs work with Downloader. \ No newline at end of file diff --git a/changelog.d/downloader/3234.docs.rst b/changelog.d/downloader/3234.docs.rst new file mode 100644 index 000000000..e5d12a5f3 --- /dev/null +++ b/changelog.d/downloader/3234.docs.rst @@ -0,0 +1 @@ +Remove API Reference for Downloader cog. \ No newline at end of file diff --git a/docs/changelog_3_1_0.rst b/docs/changelog_3_1_0.rst index d56af23ee..e067ae804 100644 --- a/docs/changelog_3_1_0.rst +++ b/docs/changelog_3_1_0.rst @@ -110,7 +110,7 @@ Downloader * ``[p]cog uninstall`` allows to uninstall multiple cogs now (`#2592`_) * ``[p]cog uninstall`` will now remove cog from installed cogs even if it can't find the cog in install path anymore (`#2595`_) * ``[p]cog install`` will not allow to install cogs which aren't suitable for installed version of Red anymore (`#2605`_) - * Cog Developers now have to use ``min_bot_version`` in form of version string instead of ``bot_version`` in info.json and they can also use ``max_bot_version`` to specify maximum version of Red, more in :doc:`framework_downloader`. (`#2605`_) + * Cog Developers now have to use ``min_bot_version`` in form of version string instead of ``bot_version`` in info.json and they can also use ``max_bot_version`` to specify maximum version of Red, more in :ref:`info-json-format`. (`#2605`_) ------ Filter diff --git a/docs/cog_downloader.rst b/docs/cog_downloader.rst deleted file mode 100644 index dfb4bdd85..000000000 --- a/docs/cog_downloader.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. Downloader Cog Reference - -Downloader Cog Reference -======================== - -.. automodule:: redbot.cogs.downloader - -.. autoclass:: redbot.cogs.downloader.downloader.Downloader - :members: diff --git a/docs/guide_cog_creation.rst b/docs/guide_cog_creation.rst index 07f6410e5..06f905efa 100644 --- a/docs/guide_cog_creation.rst +++ b/docs/guide_cog_creation.rst @@ -3,9 +3,9 @@ .. role:: python(code) :language: python -==================== -Creating cogs for V3 -==================== +======================== +Creating cogs for Red V3 +======================== This guide serves as a tutorial on creating cogs for Red V3. It will cover the basics of setting up a package for your @@ -136,6 +136,12 @@ have successfully created a cog! You can also take a look at `our cookiecutter `_, for help creating the right structure. +------------------- +Publishing your cog +------------------- + +Go to :doc:`/guide_publish_cogs` + -------------------- Additional resources -------------------- diff --git a/docs/guide_migration.rst b/docs/guide_migration.rst index 3d37f6c17..2ddec7909 100644 --- a/docs/guide_migration.rst +++ b/docs/guide_migration.rst @@ -3,9 +3,9 @@ .. role:: python(code) :language: python -==================== -Migrating Cogs to V3 -==================== +========================== +Migrating cogs from Red V2 +========================== First, be sure to read :dpy_docs:`discord.py's migration guide ` as that covers all of the changes to discord.py that will affect the migration process diff --git a/docs/framework_downloader.rst b/docs/guide_publish_cogs.rst similarity index 64% rename from docs/framework_downloader.rst rename to docs/guide_publish_cogs.rst index 612ed35ea..c5073c885 100644 --- a/docs/framework_downloader.rst +++ b/docs/guide_publish_cogs.rst @@ -1,10 +1,35 @@ -.. downloader framework reference +.. Publishing cogs for V3 -Downloader Framework -==================== +Publishing cogs for Red V3 +========================== -Info.json -********* +Users of Red install 3rd-party cogs using Downloader cog. To make your cog available +to install for others, you will have to create a git repository +and publish it on git repository hosting (for example `GitHub `_) + +Repository Template +------------------- + +We have standardized what a repository's structure should look like to better assist +our Downloader system and provide essential information to the Red portal. + +The main repository should contain at a minimum: + + - :ref:`An info.json file ` + - One folder for each cog package in the repository + + - refer to :doc:`/guide_cog_creation` for information on how to create a valid cog package + - you should also put :ref:`info.json file ` inside each cog folder + +We also recommend adding a license and README file with general information about the repository. + +For a simple example of what this might look like when finished, +take a look at `our example template `_. + +.. _info-json-format: + +Info.json format +---------------- The optional info.json file may exist inside every package folder in the repo, as well as in the root of the repo. The following sections describe the valid @@ -16,7 +41,7 @@ Keys common to both repo and cog info.json (case sensitive) - ``author`` (list of strings) - list of names of authors of the cog or repo. - ``description`` (string) - A long description of the cog or repo. For cogs, this - is displayed when a user executes ``!cog info``. + is displayed when a user executes ``[p]cog info``. - ``install_msg`` (string) - The message that gets displayed when a cog is installed or a repo is added @@ -25,7 +50,7 @@ Keys common to both repo and cog info.json (case sensitive) used for installing. - ``short`` (string) - A short description of the cog or repo. For cogs, this info - is displayed when a user executes ``!cog list`` + is displayed when a user executes ``[p]cog list`` Keys specific to the cog info.json (case sensitive) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -58,45 +83,3 @@ Keys specific to the cog info.json (case sensitive) .. warning:: Shared libraries are deprecated since version 3.2 and are marked for removal in version 3.3. -API Reference -************* - -.. automodule:: redbot.cogs.downloader.json_mixins - -.. autoclass RepoJSONMixin - :members - -.. automodule:: redbot.cogs.downloader.installable - -Installable -^^^^^^^^^^^ - -.. autoclass:: Installable - :members: - -InstalledModule -^^^^^^^^^^^^^^^ - -.. autoclass:: InstalledModule - :members: - -.. automodule:: redbot.cogs.downloader.repo_manager - -Repo -^^^^ - -.. autoclass:: Repo - :members: - -Repo Manager -^^^^^^^^^^^^ - -.. autoclass:: RepoManager - :members: - -Exceptions -^^^^^^^^^^ - -.. automodule:: redbot.cogs.downloader.errors - :members: - diff --git a/docs/index.rst b/docs/index.rst index 85c3f217e..da6b87e4a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -23,7 +23,6 @@ Welcome to Red - Discord Bot's documentation! :caption: Cog Reference: cog_customcom - cog_downloader cog_permissions .. toctree:: @@ -38,6 +37,7 @@ Welcome to Red - Discord Bot's documentation! guide_migration guide_cog_creation + guide_publish_cogs framework_apikeys framework_bank framework_bot @@ -46,7 +46,6 @@ Welcome to Red - Discord Bot's documentation! framework_commands framework_config framework_datamanager - framework_downloader framework_events framework_i18n framework_modlog