From 3febc948714b3b1ff01745f492af6e2357a7437c Mon Sep 17 00:00:00 2001
From: palmtree5 <3577255+palmtree5@users.noreply.github.com>
Date: Sun, 22 Oct 2017 17:05:47 -0800
Subject: [PATCH] [V3] migration docs (#992)

* [Docs] start on migration guide

* [Docs] add more to migration docs

* [Docs] fix imports in examples

* [Docs] add migration guide to toctree

* [Docs] add a cog creation guide

* [Docs] expand on cog packages in migration guide

* Fix typo

* [Docs] add link for modlog docs
---
 docs/framework_bank.rst     |  2 +-
 docs/guide_cog_creation.rst | 95 +++++++++++++++++++++++++++++++++++++
 docs/guide_migration.rst    | 56 ++++++++++++++++++++++
 docs/index.rst              |  2 +
 4 files changed, 154 insertions(+), 1 deletion(-)
 create mode 100644 docs/guide_cog_creation.rst
 create mode 100644 docs/guide_migration.rst

diff --git a/docs/framework_bank.rst b/docs/framework_bank.rst
index 3ddbf89e3..393fff631 100644
--- a/docs/framework_bank.rst
+++ b/docs/framework_bank.rst
@@ -16,7 +16,7 @@ Basic Usage
 
 .. code-block:: python
 
-    from core import bank
+    from redbot.core import bank
 
     class MyCog:
         @commands.command()
diff --git a/docs/guide_cog_creation.rst b/docs/guide_cog_creation.rst
new file mode 100644
index 000000000..2766e3fc2
--- /dev/null
+++ b/docs/guide_cog_creation.rst
@@ -0,0 +1,95 @@
+.. Making cogs for V3
+
+.. role:: python(code)
+    :language: python
+
+====================
+Creating cogs for 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
+cog and the basics of setting up the file structure. We will
+also point you towards some further resources that may assist
+you in the process.
+
+---------------
+Getting started
+---------------
+
+To start off, be sure that you have installed Python 3.5 or higher (if you
+are on Windows, stick with 3.5). Open a terminal or command prompt and type
+:code:`pip install --process-dependency-links -U https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=redbot[test]`
+(note that if you get an error with this, try again but put :code:`python -m` in front of the command
+This will install the latest version of V3. 
+
+--------------------
+Setting up a package
+--------------------
+
+To set up a package, we would just need to create a new folder.
+This should be named whatever you want the cog to be named (for
+the purposes of this example, we'll call this :code:`mycog`).
+In this folder, create three files: :code:`__init__.py`,
+:code:`mycog.py`, and :code:`info.json`. Open the folder in
+a text editor or IDE (examples include `Sublime Text 3 <https://www.sublimetext.com/>`_,
+`Visual Studio Code <https://code.visualstudio.com/>`_, `Atom <https://atom.io/>`_, and
+`PyCharm <http://www.jetbrains.com/pycharm/>`_).
+
+--------------
+Creating a cog
+--------------
+
+With your package opened in a text editor or IDE, open :code:`mycog.py`.
+In that file, place the following code:
+
+.. code-block:: python
+
+    from discord.ext import commands
+
+    class Mycog:
+        """My custom cog"""
+
+        @commands.command()
+        async def mycom(self, ctx):
+            """This does stuff!"""
+            # Your code will go here
+            await ctx.send("I can do stuff!")
+
+Open :code:`__init__.py`. In that file, place the following:
+
+.. code-block:: python
+
+    from .mycog import Mycog
+
+    def setup(bot):
+        bot.add_cog(Mycog())
+
+Make sure that both files are saved.
+
+----------------
+Testing your cog
+----------------
+
+To test your cog, you will need a running instance of V3.
+Assuming you installed V3 as outlined above, run :code:`redbot-setup`
+and provide the requested information. Once that's done, run Red
+by doing :code:`redbot <instance name> --dev` to start Red.
+Complete the inital setup by providing a valid token and setting a
+prefix. Once the bot has started up, use the link provided in the
+console to add it to a server (note that you must have the
+:code:`Manage Server` (or :code:`Administrator`) permission to add bots
+to a server). Once it's been added to a server, find the full path
+to the directory where your cog package is located. In Discord, do
+:code:`[p]addpath <path_to_folder_containing_package>`, then do
+:code:`[p]load mycog`. Once the cog is loaded, do :code:`[p]mycom`
+The bot should respond with :code:`I can do stuff!`. If it did, you
+have successfully created a cog!
+
+--------------------
+Additional resources
+--------------------
+
+Be sure to check out the `migration guide </guide_migration>`_ for some resources
+on developing cogs for V3. This will also cover differences between V2 and V3 for
+those who developed cogs for V2.
diff --git a/docs/guide_migration.rst b/docs/guide_migration.rst
new file mode 100644
index 000000000..165825885
--- /dev/null
+++ b/docs/guide_migration.rst
@@ -0,0 +1,56 @@
+.. V3 Migration Guide
+
+.. role:: python(code)
+    :language: python
+
+====================
+Migrating Cogs to V3
+====================
+
+First, be sure to read `discord.py's migration guide <http://discordpy.readthedocs.io/en/rewrite/migrating.html>`_
+as that covers all of the changes to discord.py that will affect the migration process
+
+----------------
+Red as a package
+----------------
+
+V3 makes Red a package that is installed with :code:`pip`. Please
+keep this in mind when writing cogs as this affects how imports 
+should be done (for example, to import :code:`pagify` in V2, one
+would do :code:`from .utils.chat_formatting import pagify`; in
+V3, this becomes :code:`from redbot.core.utils.chat_formatting import pagify`)
+
+----------------
+Cogs as packages
+----------------
+
+V3 makes cogs into packages. See `the cog creation guide </guide_cog_creation>`_
+for more on how to create packages for V3
+
+------
+Config
+------
+
+Config is V3's replacement for :code:`dataIO`. Instead of fiddling with
+creating config directories and config files as was done in V2, V3's
+Config handles that whilst allowing for easy storage of settings on a
+per-server/member/user/role/channel or global basis. Be sure to check
+out :doc:`/framework_config` for the API docs for Config as well as a
+tutorial on using Config.
+
+----
+Bank
+----
+
+Bank in V3 has been split out from Economy. V3 introduces the ability
+to have a global bank as well as the ability to change the bank name
+and the name of the currency. Be sure to checkout :doc:`/framework_bank`
+for more on Bank
+
+-------
+Mod Log
+-------
+
+V3 introduces Mod Log as an API, thus allowing for cogs to add custom case
+types that will appear in a server's mod log channel. Be sure to checkout
+:doc:`/framework_modlog` for more on Mod Log` 
diff --git a/docs/index.rst b/docs/index.rst
index f6f65926c..69519b91e 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -27,6 +27,8 @@ Welcome to Red - Discord Bot's documentation!
     :maxdepth: 2
     :caption: Red Development Framework Reference:
 
+    guide_migration
+    guide_cog_creation
     framework_bank
     framework_cogmanager
     framework_config