Merge branch 'master' into mikejo-updates

Author: mikeblome

docs/python/debugging-mixed-mode.md

@@ -32,7 +32,7 @@ translation.priority.ht:
 
 # Debugging Python and C++ Together
 
-Most regular Python debuggers support debugging of only Python code. In practice, however, Python is used in conjunction with C or C++ where high performance or the ability to directly invoke platform APIs is required (see [Creating a C++ Extension for Python](cpp-and-python.md) for an example. Visual Studio provides integrated, simultaneous mixed-mode debugging for Python and native C/C++, with combined call stacks, the ability to step between Python and native code, breakpoints in either type of code, and the ability to see Python representations of objects in native frames and vice versa:
+Most regular Python debuggers support debugging of only Python code. In practice, however, Python is used in conjunction with C or C++ where high performance or the ability to directly invoke platform APIs is required (see [Creating a C++ Extension for Python](cpp-and-python.md) for an example. When a Python project is loaded, Visual Studio provides integrated, simultaneous mixed-mode debugging for Python and native C/C++, with combined call stacks, the ability to step between Python and native code, breakpoints in either type of code, and the ability to see Python representations of objects in native frames and vice versa:
 
 ![Mixed-mode debugging](media/mixed-mode-debugging.png) 
 
@@ -41,7 +41,7 @@ For an introduction to building, testing, and debugging native C modules with Vi
 > [!VIDEO https://www.youtube.com/embed/D9RlT06a1EI]
 
 > [!Note]
-> Mixed mode debugging is not available with Python Tools for Visual Studio 1.x.
+> Mixed-mode debugging is not available with Python Tools for Visual Studio 1.x.
 
 ## Enabling mixed-mode debugging
 
@@ -64,6 +64,13 @@ For an introduction to building, testing, and debugging native C modules with Vi
 
 1. You may also want to have the Python source code itself on hand. For standard Python, this can be obtained from [https://www.python.org/downloads/source/](https://www.python.org/downloads/source/). Download the archive appropriate for your version and extract it to a folder. You'll point Visual Studio to specific files in that folder at whatever point it prompts you.
 
+> [!Note]
+> Mixed-mode debugging as described here is enabled only when you have a Python project loaded into Visual Studio. That project determines the Visual Studio's debugging mode, which is what makes the mixed-mode option available. If, however, you have a C++ project loaded (as you would when [embedding Python in another application as described on python.org](https://docs.python.org/3/extending/embedding.html), then Visual Studio uses the native C++ debugger that doesn't support mixed-mode debugging.
+>
+> In this case, start the C++ project without debugging (**Debug > Start without debugging** or Ctrl+F5), and then use **Debug > Attach to Process...**. In the dialog that appears, select the appropriate process, then use the **Select...** button to open the **Select Code Type** dialog in which you can select Python as shown below. Select **OK** to close that dialog, then **Attach** to start the debugger. Note that you may need to introduce a suitable pause or delay in the C++ app to ensure that it doesn't call the Python you want to debug before you can attach the debugger.
+>
+> ![Selecting Python as the debugging type when attaching a debugger](media/mixed-mode-debugging-attach-type.png)
+
 ## Mixed-mode specific features
 
 - [Combined call stack](#combined-call-stack)

docs/python/media/mixed-mode-debugging-attach-type.png

@@ -36,8 +36,8 @@ Python in Visual Studio makes it easy to manage multiple Python environments and
 
 Note: if you're new to Python in Visual Studio, see the following topics first as this present discussion relies upon them:
 
-    - [Working with Python in Visual Studio](python-in-visual-studio.md)
-    - [Installing Python support in Visual Studio](installation.md)
+- [Working with Python in Visual Studio](python-in-visual-studio.md)
+- [Installing Python support in Visual Studio](installation.md)
 
 A Python *environment*, in which you always run Python code, consists of an interpreter, a library (typically the Python Standard Library), and a set of installed packages. Together these determine which language constructs and syntax are valid, what operating-system functionality you can access, and which packages you can use.
 

docs/python/python-environments.md

@@ -51,6 +51,9 @@ RTVS will not install if you have only the Visual Studio Shell that's included w
 
 ## Installing RTVS in Visual Studio 2017
 
+> [!Important]
+> Installing RTVS in Visual Studio 2017 on Windows 7 is currently blocked as desribed on [GitHub issue #3561](https://github.com/Microsoft/RTVS/issues/3561). This will be resolved in the 15.3 update to Visual Studio 2017.
+
 1. Run the Visual Studio installer.
 2. Select the **Data science and analytical applications** workload: