Reword more

Author: encukou

Doc/extending/first-extension-module.rst

@@ -1,29 +1,31 @@
 .. highlight:: c
 
 
+.. _first-extension-module:
+
 *********************************
 Your first C API extension module
 *********************************
 
 This tutorial will take you, line by line, through creating a simple
 Python extension module written in C or C++.
 
-This document assumes basic knowledge about Python: you should be able to
-define functions in Python code before writing them in another language.
+The tutorial assumes basic knowledge about Python: you should be able to
+define functions in Python code before starting to write them in C.
 See :ref:`tutorial-index` for an introduction to Python itself.
 
-It also assumes a working knowledge of the C language.
-We will use several concepts that a C beginner would not be expected to know,
-like ``static`` functions or linkage declarations, but the tutorial should
-be useful for anyone who can write a basic C library.
+The tutorial should be useful for anyone who can write a basic C library.
+While we will mention several concepts that a C beginner would not be expected
+to know, like ``static`` functions or linkage declarations, understanding these
+is not necessary for success.
 
-As a word warning before we begin: the compilation of an extension module can
-be tricky, as it depends on how your system is set up, and on how your Python
-is installed.
+As a word warning before we begin: after the code is written, you will need to
+compile it with the right tools and settings for your system.
 It is generally best to use a third-party tool to handle the details.
-This is covered in later chapters.
+This is covered in later chapters, not in this tutorial.
 
-The tutorial assumes that you use a Unix system (including macOS) or Windows.
+The tutorial assumes that you use a Unix-like system (including macOS and
+Linux) or Windows.
 
 .. include:: ../includes/tutorial-new-api.rst
 
@@ -338,8 +340,8 @@ This macro expands to a variable definition like
 ``static PyABIInfo abi_info = { ... data ... };``
 
 
-The slot table and export hook
-==============================
+The slot table
+==============
 
 Now, let's fit all the pieces of our module together.
 
@@ -349,15 +351,19 @@ an array of :c:type:`PyModuleDef_Slot` structures.
 Like with the method table, a zero-filled *sentinel* marks the end.
 
 Besides the method table, this "slot table" will contain the module's
-top-level information: the name, a docstring, and the
-ABI compatibility slot we defined earlier:
+top-level information: the name, a docstring, and the ABI compatibility
+information we've just defined:
 
 .. literalinclude:: ../includes/capi-extension/spammodule-01.c
    :start-after: /// Module slot table
    :end-before: ///
 
-This structure, in turn, must be passed to the interpreter in the module's
-:ref:`export hook <extension-export-hook>` function.
+
+Module export hook
+==================
+
+The :c:type:`PyModuleDef_Slot` array must be passed to the interpreter in the
+module's :ref:`export hook <extension-export-hook>` function.
 The hook must be named :c:func:`!PyModExport_name`, where *name* is the name
 of the module, and it should be the only non-\ ``static`` item defined in the
 module file.

Doc/extending/index.rst

@@ -4,7 +4,7 @@
   Extending and Embedding the Python Interpreter
 ##################################################
 
-This tutorial describes how to write modules in C or C++ to extend the Python
+This document describes how to write modules in C or C++ to extend the Python
 interpreter with new modules.  Those modules can do what Python code does --
 define functions, object types and methods -- but also interact with native
 libraries or achieve better performance by avoiding the overhead of an
@@ -42,14 +42,32 @@ source file by including the header ``"Python.h"``.
    extension module.
 
 
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   first-extension-module.rst
+   extending.rst
+   newtypes_tutorial.rst
+   newtypes.rst
+   building.rst
+   windows.rst
+   embedding.rst
+
+
 Recommended third party tools
 =============================
 
-This guide only covers the basic tools for creating extensions provided
+This document only covers the basic tools for creating extensions provided
 as part of this version of CPython. Some :ref:`third party tools
 <c-api-tools>` offer both simpler and more sophisticated approaches to creating
 C and C++ extensions for Python.
 
+While this document is aimed at extension authors, it should also be helpful to
+the authors of such tools.
+For example, the tutorial module can serve as a simple test case for a build
+tool or sample expected output of a code generator.
+
 
 C API Tutorial
 ==============
@@ -59,30 +77,22 @@ using the Python C API -- that is, using the basic tools provided
 as part of this version of CPython.
 
 
-.. toctree::
-   :maxdepth: 2
-   :numbered:
-
-   first-extension-module.rst
+#. :ref:`first-extension-module`
 
 
-Creating extensions without third party tools
-=============================================
+Guides for intermediate topics
+==============================
 
 This section of the guide covers creating C and C++ extensions without
 assistance from third party tools. It is intended primarily for creators
 of those tools, rather than being a recommended way to create your own
 C extensions.
 
-.. toctree::
-   :maxdepth: 2
-   :numbered:
-
-   extending.rst
-   newtypes_tutorial.rst
-   newtypes.rst
-   building.rst
-   windows.rst
+* :ref:`extending-intro`
+* :ref:`defining-new-types`
+* :ref:`new-types-topics`
+* :ref:`building`
+* :ref:`building-on-windows`
 
 Embedding the CPython runtime in a larger application
 =====================================================
@@ -92,8 +102,4 @@ interpreter as the main application, it is desirable to instead embed
 the CPython runtime inside a larger application. This section covers
 some of the details involved in doing that successfully.
 
-.. toctree::
-   :maxdepth: 2
-   :numbered:
-
-   embedding.rst
+* :ref:`embedding`

Doc/includes/capi-extension/spammodule-01.c

@@ -42,7 +42,7 @@ static PyModuleDef_Slot spam_module[] = {
     {Py_mod_name, "spam"},
     {Py_mod_doc, PyDoc_STR("A wonderful module with an example function")},
     {Py_mod_methods, spam_methods},
-    {0, NULL}  /* Sentinel */
+    {0, NULL}
 };