Move doc -> docs.

docs/source/setup-tools.rst

@@ -0,0 +1,135 @@
+Setting up the environment
+==========================
+
+This page will get you started for creating a MO2 python plugin. If you have troubles getting
+everything setup, feel free to come by our discord server at `https://discord.gg/cYwdcxj <https://discord.gg/cYwdcxj>`_.
+
+Required tools
+--------------
+
+It is possible to write a MO2 python plugin using any text editor, but this guide will focus on
+`Visual Studio Code <https://code.visualstudio.com/>`_.
+This guide assumes that:
+
+- You have `Visual Studio Code <https://code.visualstudio.com/>`_ installed with the
+  `Python extension <https://marketplace.visualstudio.com/items?itemName=ms-python.python>`_.
+- You have Python installed: https://www.python.org/downloads/.
+
+  - It is recommended but not mandatory to use the Python version that is used by MO2.
+    You can check the ``pythonXX.dll`` in the MO2 installation folder to find the Python version used by MO2 (``python38.dll`` means Python 3.8).
+- You obviously need a valid MO2 installation: https://github.com/modorganizer2/modorganizer/releases
+
+  - This guide is written for MO2 ≥ 2.3.0.
+
+**Note:** In the following, I will refer to the MO2 installation directory as ``$MO2DIR``. So if you
+installed MO2 at `C:\MO2` and you are asked to copy a file to ``$MO2DIR/plugins``, it refers to ``C:\MO2\plugins``.
+
+Preparation
+-----------
+
+**Note:** This part is optional but highly recommended if you want a proper environment to work with.
+Everything here is written to be as simple as possible but you can of course adapt it to your preferences: use a python virtual
+environment, use workspace settings instead of global ones, etc.
+
+1. Get the ``mobase`` stubs
+...........................
+
+``mobase`` is the MO2 Python module. The module is written in C++ and thus cannot be read directly by tools such
+as ``flake8`` or ``mypy``.
+Instead, we provide `stubs <https://stackoverflow.com/questions/59051631/what-is-the-use-of-stub-files-pyi-in-python>`_
+which can be used for auto-completion or type-checking.
+
+The stubs for ``mobase`` are available at https://github.com/ModOrganizer2/pystubs-generation/tree/master/stubs.
+You want to download the ``mobase.pyi`` file in the folder corresponding to your MO2 version and put it under ``$MO2DIR/plugins/data``.
+
+**Note:** It is possible to put the stubs in a different location, but we are going to use ``$MO2DIR/plugins/data`` for PyQt5,
+so we might as well use it for the stubs.
+
+2. Configure Visual Studio Code for ``mobase``
+..............................................
+
+We are going to configure Visual Studio Code to have auto-completion and linting (error and type checking)
+for the MO2 Python module.
+Open ``settings.json`` (Ctrl+Shift+P, then "Open Settings (JSON)"), and add the following entries:
+
+.. code-block:: json-object
+
+    "python.linting.enabled": true,
+    "python.linting.mypyEnabled": true,
+    "python.linting.flake8Enabled": true,
+    "python.autoComplete.extraPaths": [
+        "$MO2DIR\\plugins\\data",
+    ]
+
+3. Configure ``mypy`` to find the ``mobase`` stubs
+..................................................
+
+There are multiply way to configure ``mypy``:
+
+1. You can create a ``mypy.ini`` file somewhere containing:
+
+.. code-block:: ini
+
+    [mypy]
+    mypy_path = $MO2DIR\plugins\data
+
+And then add the following to ``settings.json`` (with the correct path):
+
+.. code-block:: json-object
+
+    "python.linting.mypyArgs": [
+        "--config-file=path-to-mypy.ini",
+    ]
+
+2. You can set the ``MYPYPATH`` environment variable to ``$MO2DIR\plugins\data`` (this requires
+restarting VS code).
+
+Testing the setup
+-----------------
+
+Create a new Python file in Visual Studio Code, and paste the following content (if you create
+the file in ``$MO2DIR\plugins``, do not forget to delete it after since it is not a valid
+plugin):
+
+.. code-block:: python
+
+    import mobase
+
+
+    class MyPlugin(mobase.IPluginTool):
+        def __init__(self):
+            super().__init__()
+
+        def init(self, organizer: mobase.IOrganizer) -> bool:
+            organizer.dow  # (1)
+            return True
+
+        def name(self) -> int:
+            return 0
+
+
+    def createPlugin() -> mobase.IPlugin:
+        return MyPlugin()
+
+
+If your setup is valid, here is what you should have.
+
+- You should see the following (with the errors underlined):
+
+.. image:: images/check-setup-1.png
+
+- If you press ``Ctrl+Space`` after ``.down`` (1), you should see the following
+  meaning that auto-complete is working:
+
+.. image:: images/check-setup-2.png
+
+- In the error window (click |error-window| on the status bar), you should see
+  the 3 following errors:
+
+.. image:: images/check-setup-3.png
+
+If everything is as above, you can delete the test file and move on to writting
+your own plugin!
+
+
+.. |error-window| image:: images/error-window.png