First pass at documentation reform.

1 files changed, 112 insertions, 0 deletions

diff --git a/docs/intro.rst b/docs/intro.rst
new file mode 100644
index 00000000..b3804be1
--- /dev/null
+++ b/docs/intro.rst
@@ -0,0 +1,112 @@
+.. currentmodule:: discord
+
+.. _intro:
+
+Introduction
+==============
+
+This is the documentation for discord.py, a library for Python to aid
+in creating applications that utilise the Discord API.
+
+Prerequisites
+---------------
+
+discord.py works with Python 3.4.2 or higher. Support for earlier versions of Python
+is not provided. Python 2.7 or lower is not supported. Python 3.3 is not supported
+due to one of the dependencies (``aiohttp``) not supporting Python 3.3.
+
+
+.. _installing:
+
+Installing
+-----------
+
+You can get the library directly from PyPI: ::
+
+    python3 -m pip install -U discord.py
+
+If you are using Windows, then the following should be used instead: ::
+
+    py -3 -m pip install -U discord.py
+
+
+To get voice support, you should use ``discord.py[voice]`` instead of ``discord.py``, e.g. ::
+
+    python3 -m pip install -U discord.py[voice]
+
+On Linux environments, installing voice requires getting the following dependencies:
+
+- libffi
+- libnacl
+- python3-dev
+
+For a debian-based system, the following command will help get those dependencies:
+
+.. code-block:: shell
+
+    $ apt install libffi-dev libnacl-dev python3-dev
+
+Remember to check your permissions!
+
+Virtual Environments
+~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes we don't want to pollute our system installs with a library or we want to maintain
+different versions of a library than the currently system installed one. Or we don't have permissions to
+install a library along side with the system installed ones. For this purpose, the standard library as
+of 3.3 comes with a concept called "Virtual Environment" to help maintain these separate versions.
+
+A more in-depth tutorial is found on `the official documentation. <https://docs.python.org/3/tutorial/venv.html>`_
+
+However, for the quick and dirty:
+
+1. Go to your project's working directory:
+
+    .. code-block:: shell
+
+        $ cd your-bot-source
+        $ python3 -m venv bot-env
+
+2. Activate the virtual environment:
+
+    .. code-block:: shell
+
+        $ source bot-env/bin/activate
+
+    On Windows you activate it with:
+
+    .. code-block:: shell
+
+        $ bot-env\Scripts\activate.bat
+
+3. Use pip like usual:
+
+    .. code-block:: shell
+
+        $ pip install -U discord.py
+
+Congratulations. You now have a virtual environment all set up without messing with your system installation.
+
+Basic Concepts
+---------------
+
+discord.py revolves around the concept of :ref:`events <discord-api-events>`.
+An event is something you listen to and then respond to. For example, when a message
+happens, you will receive an event about it and you can then respond to it.
+
+A quick example to showcase how events work:
+
+.. code-block:: python
+
+    import discord
+
+    class MyClient(discord.Client):
+        async def on_ready(self):
+            print('Logged on as {0}!'.format(self.user))
+
+        async def on_message(self, message):
+            print('Message from {0.author}: {0.content}'.format(message))
+
+    client = MyClient()
+    client.run('my token goes here')
+