docs: contributing: editors: VSCode

Fixes: #494
Closes: #502

Signed-off-by: John Andersen <[email protected]>

Author: Naeemkh

CHANGELOG.md

@@ -23,6 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Support for operations without inputs.
 - Partial doctestable examples to `features.py`
 - Doctestable examples for `BaseSource`
+- Instructions for setting up debugging environment in VSCode
 ### Fixed
 - New model tutorial mentions file paths that should be edited.
 - DataFlow is no longer a dataclass to prevent it from being exported

docs/contributing/editors/index.rst

@@ -0,0 +1,18 @@
+Setting Up Your Editor
+======================
+
+Maintaining proper execution of DFFML API both in development and deployment
+levels is the top priority of the development team. DFFML modules are tightly
+coupled; as a result, the debugging process can be complicated.
+After identifying the potential problems or encountering an error during
+execution time, developers need to reproduce the problem and also be able to
+acquire knowledge about the program and state of the variables, specifically
+a couple of steps before the problems. This requires setting up a debugging
+environment. In this section, setting up a debugger for DFFML in different
+editors is presented.
+
+.. toctree::
+    :glob:
+    :maxdepth: 2
+
+    vscode

docs/contributing/editors/vscode.rst

@@ -0,0 +1,82 @@
+Setting up debugging in Visual Studio Code (VSCode)
+===================================================
+
+`VSCode <https://code.visualstudio.com/>`_ provides powerful tools for
+debugging support. For this project, we use a Python extension. For more
+details about debugging configurations for Python apps in VSCode, see this
+`link <https://code.visualstudio.com/docs/python/debugging>`_.
+
+If you are planning on contributing to the project, or track your debugging
+process, it is a better idea to have your own copy of DFFML on your Github
+account. For more details about setting up your git repository,
+read :doc:`git` page.
+
+After setting up the version controlling configurations, you need to install
+DFFML. See :doc:`dev_env` page for installing details in the development mode.
+
+Open the VSCode app, on the menu bar, click on ``File`` then choose
+``Open Folder``. Locate DFFML folder and open it. Inside the folder in VSCode,
+select ``setup.py`` file. This helps VSCode to retrieve your Python environment
+(either base or any virtual environment) that you setup. You can close the
+``setup.py`` file.
+
+Go to the menu bar and click on ``Run``, then select ``Add configuration``.
+Choose Python from the drop-down menu and then select ``module``. Inside the
+module text input field type ``dffml`` and press Enter. This will create a
+``launch.json`` file under the ``.vscode`` folder.
+
+It should be similar to the following:
+
+.. code-block:: console
+
+    {
+        // Use IntelliSense to learn about possible attributes.
+        // Hover to view descriptions of existing attributes.
+        // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+        "version": "0.2.0",
+        "configurations": [
+            {
+                "name": "Python: Module",
+                "type": "python",
+                "request": "launch",
+                "module": "dffml"
+            }
+        ]
+    }
+
+``dffml`` module needs arguments to run. Add arguments as a key-value pair into
+the embedded configurations container. Here is the example ``launch.json`` file
+for the :doc:`/quickstart/model` example.
+
+.. code-block:: console
+
+    {
+        // Use IntelliSense to learn about possible attributes.
+        // Hover to view descriptions of existing attributes.
+        // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+        "version": "0.2.0",
+        "configurations": [
+            {
+                "name": "Python: Module",
+                "type": "python",
+                "request": "launch",
+                "module": "dffml",
+                "args": [
+                    "train",
+                    "-model", "scikitlr",
+                    "-model-features", "Years:int:1", "Expertise:int:1",
+                    "Trust:float:1",
+                    "-model-predict", "Salary:float:1",
+                    "-sources", "f=csv",
+                    "-source-filename", "training.csv"
+                ]
+            }
+        ]
+    }
+
+Save the file and click on the ``Run`` at the menu bar, and then click on
+``Start Debugging``. The code should run successfully to the end. You can add
+``"stopOnEntry": true,`` in the configurations container to break immediately
+when the program launches or you can use break point to stop at any arbitrary
+point in the code. Read more about debugging a Python code in
+VSCode `here <https://code.visualstudio.com/docs/python/debugging>`_.

docs/contributing/git.rst

@@ -1,23 +1,34 @@
 Git and GitHub
 ==============
 
-We encourage people to commit code and push it up to GitHub often. That way, if
-you're having trouble with something you can send others a link to your code
+We encourage people to commit code and push it up to GitHub often. That way,
+if you're having trouble with something you can send others a link to your code
 where they can easily get an idea of what might be going wrong. Don't worry if
 it's nowhere near complete! Asking each other for help just gets us to working
 code faster!
 
-Working On A Branch
--------------------
+In your local computer, create a new folder for the project, open terminal
+(Mac and Linux) or `Gitbash <https://gitforwindows.org/>`_ (Windows) and
+navigate to the folder. Using the following command, clone DFFML
+repository to this folder.
 
-Be sure to checkout a new branch to do your work on.
+.. code-block:: console
+
+    $ git clone [email protected]:intel/dffml
+
+Navigate inside the DFFML folder and run the following command to make sure
+that you have the latest version of the code. Be sure to checkout a new branch
+to do your work on.
 
 .. code-block:: console
 
     $ git fetch origin
     $ git checkout -b my_new_thing origin/master
 
-You'll need to fork the repo on GitHub too. Then add that as a remote.
+You need to have your own version of DFFML to track your work. Log in to your
+Github account and go to `DFFML <https://github.com/intel/dffml>`_ repository.
+There is a ``Fork`` tab at the top right of the page. Click on the button to
+fork a copy into your Github account.
 
 .. note::
 
@@ -33,8 +44,8 @@ Once you've committed a change on that branch you can push it to your fork.
 
     $ git push -u $USER my_new_thing
 
-Then you can keep committing on this branch and just use ``git push`` to send your
-new commits to GitHub.
+Then you can keep committing on this branch and just use ``git push`` to send
+your new commits to GitHub.
 
 Issue and Pull Request title formatting
 ---------------------------------------

docs/contributing/index.rst

@@ -19,4 +19,5 @@ or post in the `Gitter Chat <https://gitter.im/dffml/community>`_.
     testing
     docs
     debugging
+    editors/index
     maintainers