From 375f35be0688da0fc0f27afc4faea76590d7c24d Mon Sep 17 00:00:00 2001
From: "Miss Islington (bot)"
 <31488909+miss-islington@users.noreply.github.com>
Date: Fri, 2 Aug 2019 10:49:38 -0700
Subject: [PATCH] bpo-36487: Make C-API docs clear about what the main
 interpreter is. (gh-15080)

(cherry picked from commit 854d0a4b98b13629252e21edaf2b785b429e5135) (gh-12666)

Co-authored-by: Joannah Nanjekye <33177550+nanjekyejoannah@users.noreply.github.com>
---
 Doc/c-api/init.rst                               | 16 ++++++++++++----
 .../2019-04-02-19-23-00.bpo-36487.Jg6-MG.rst     |  1 +
 2 files changed, 13 insertions(+), 4 deletions(-)
 create mode 100755 Misc/NEWS.d/next/Documentation/2019-04-02-19-23-00.bpo-36487.Jg6-MG.rst

diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index a0ac4d21d13..4985a1d867e 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -1141,10 +1141,18 @@ Sub-interpreter support
 
 While in most uses, you will only embed a single Python interpreter, there
 are cases where you need to create several independent interpreters in the
-same process and perhaps even in the same thread.  Sub-interpreters allow
-you to do that.  You can switch between sub-interpreters using the
-:c:func:`PyThreadState_Swap` function.  You can create and destroy them
-using the following functions:
+same process and perhaps even in the same thread. Sub-interpreters allow
+you to do that.
+
+The "main" interpreter is the first one created when the runtime initializes.
+It is usually the only Python interpreter in a process.  Unlike sub-interpreters,
+the main interpreter has unique process-global responsibilities like signal
+handling.  It is also responsible for execution during runtime initialization and
+is usually the active interpreter during runtime finalization.  The
+:c:func:`PyInterpreterState_Main` funtion returns a pointer to its state.
+
+You can switch between sub-interpreters using the :c:func:`PyThreadState_Swap`
+function. You can create and destroy them using the following functions:
 
 
 .. c:function:: PyThreadState* Py_NewInterpreter()
diff --git a/Misc/NEWS.d/next/Documentation/2019-04-02-19-23-00.bpo-36487.Jg6-MG.rst b/Misc/NEWS.d/next/Documentation/2019-04-02-19-23-00.bpo-36487.Jg6-MG.rst
new file mode 100755
index 00000000000..c8eb05b6c79
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2019-04-02-19-23-00.bpo-36487.Jg6-MG.rst
@@ -0,0 +1 @@
+Make C-API docs clear about what the "main" interpreter is.
\ No newline at end of file