Merge branch 'master' of https://github.com/ericremoreynolds/excelpython

ericremoreynolds · ericremoreynolds · commit ef25a0b0d64c · 2014-09-29T12:13:25.000+02:00
diff --git a/README.md b/README.md
@@ -20,6 +20,10 @@ Check out the [tutorials](docs/) to get started! The only prerequisites are Exce
 
 ExcelPython is a lightweight, easily distributable library for interfacing Excel and Python. It enables easy access to Python scripts from Excel VBA, allowing you to substitute VBA with Python for complex automation tasks which would be facilitated by Python's extensive standard library while sparing you the complexities of Python COM programming.
 
+Do you like ExcelPython and find it useful? If so please consider donating something to support its continued development and get your name on the donor list!
+
+<a href='https://pledgie.com/campaigns/26772'><img alt='Click here to lend your support to: ExcelPython and make a donation at pledgie.com !' src='https://pledgie.com/campaigns/26772.png?skin_name=chrome' border='0' ></a>
+
 ### Help me!
 
 Check out the [docs](docs/) folder for tutorials to help you get started and links to other resources. Failing that, try the [issues section](https://github.com/ericremoreynolds/excelpython/issues?q=) or the [discussion forum on SourceForge](https://sourceforge.net/p/excelpython/discussion/general/).
diff --git a/docs/Readme.md b/docs/Readme.md
@@ -21,4 +21,5 @@ If you encounter any issues in getting the add-in set up consult the [troublesho
 
 **Learn how to analyse the problem when something goes wrong**
 
+* [Debugging](tutorials/Debugging01.md)
 * [Troubleshooting](tutorials/Troubleshooting01.md)
diff --git a/docs/tutorials/Debugging01.md b/docs/tutorials/Debugging01.md
@@ -0,0 +1,65 @@
+## Debugging code with ExcelPython
+
+ExcelPython does not have any special provision for debugging Python code because it is fully compatible with existing Python debugging tools. Here we will see how to set up a couple of the most widely-used ones, [Python Tools for Visual Studio](#debugging-with-python-tools-for-visual-studio) and [PyDev](#debugging-with-eclipse-and-pydev).
+
+## Debugging with Python Tools for Visual Studio
+
+On Windows it is possible to debug Python scripts in Microsoft Visual Studio using an add-in called [Python Tools for Visual Studio](http://pytools.codeplex.com/) (PTVS). To get set up (full instructions can be found on the PTVS website) you need to
+
+1. Install a recent version of Visual Studio, either Express or a commercial license.
+2. Download and install the relevant distribution of the PTVS add-in
+3. Install the PTVS debug package into your Python distribution
+4. Prepare your Python script to enable debugging in Visual Studio.
+
+Assuming you've done steps 1 and 2, step 3 can be achieved using [PIP](https://pypi.python.org/pypi/pip).
+
+```
+C:\>pip install ptvsd
+Downloading/unpacking ptvsd
+  Running setup.py (path:c:\docume~1\user\locals~1\temp\pip_build_user\ptvsd\setup.py) egg_info for package ptvsd
+
+Installing collected packages: ptvsd
+  Running setup.py install for ptvsd
+
+Successfully installed ptvsd
+Cleaning up...
+```
+
+Now you should be able to `import ptvsd` in your Python interpreter.
+
+Let's see how to prepare a [basic script](./Addin01.md) for debugging with PTVS
+
+```python
+# Book1.py
+from xlpython import *
+
+# Add these two lines
+import ptvsd
+ptvsd.enable_attach(secret='cows')
+
+@xlfunc
+def DoubleSum(x, y):
+	return 2 * (x + y)
+```
+
+These to lines enable us to attach the Visual Studio debugger to the Python script, so that we can debug it. Note that the Python process itself must be running for this to work, and ExcelPython does not launch it until it is needed - so just to make sure that it is running and that the `Book1.py` script is loaded, click 'Import Python UDFs'.
+
+At this point you may need to unblock a port on the Windows firewall:
+
+![image](https://cloud.githubusercontent.com/assets/5197585/4387988/f02fbbe8-43e4-11e4-997e-31f12adbdf98.png)
+
+Having done this you should now be in a position to attach the Visual Studio debugger to the Python script. To do this:
+* open the Debug > Attach to Process dialog
+* select 'Python remote debugging' as the transport
+* specify the relevant qualifier in the 'Qualifier' box, for example `cows@localhost`
+* click refresh and select the Python process
+
+![image](https://cloud.githubusercontent.com/assets/5197585/4388048/e5ae4c06-43e5-11e4-8b24-300aa0ab3d4e.png)
+
+Now you can set breakpoints in the code and the next time your function is invoked from Excel, the execution will be interrupted when the breakpoint is hit.
+
+![image](https://cloud.githubusercontent.com/assets/5197585/4388088/59fefbaa-43e6-11e4-945a-31d66d3e2730.png)
+
+## Debugging with Eclipse and PyDev
+
+Coming soon!

Original file line number	Diff line number	Diff line change
`@@ -21,4 +21,5 @@ If you encounter any issues in getting the add-in set up consult the [troublesho`
`21`	`21`
`22`	`22`	`Learn how to analyse the problem when something goes wrong`
`23`	`23`
	`24`	`+* [Debugging](tutorials/Debugging01.md)`
`24`	`25`	`* [Troubleshooting](tutorials/Troubleshooting01.md)`