From 42c11cf36de802791d25bb0cf3a5890f6a7026cb Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Wed, 10 Jul 2019 23:32:33 -0400 Subject: [PATCH 1/4] Docs: Add RST directives to c-api/intro#Include_Files Adds the following directives to the "Include Files" section: code, important, and note. Also improves the phrasing in the section where a note was added, on lines 99-101. --- Doc/c-api/intro.rst | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index a1c8d34a7ea02f..3db0b81b498968 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -46,7 +46,9 @@ Include Files ============= All function, type and macro definitions needed to use the Python/C API are -included in your code by the following line:: +included in your code by the following line: + +.. code:: c #define PY_SSIZE_T_CLEAN #include @@ -69,10 +71,12 @@ standard headers) have one of the prefixes ``Py`` or ``_Py``. Names beginning with ``_Py`` are for internal use by the Python implementation and should not be used by extension writers. Structure member names do not have a reserved prefix. -**Important:** user code should never define names that begin with ``Py`` or -``_Py``. This confuses the reader, and jeopardizes the portability of the user -code to future Python versions, which may define additional names beginning with -one of these prefixes. +.. important:: + + User code should never define names that begin with ``Py`` or + ``_Py``. This confuses the reader, and jeopardizes the portability of the user + code to future Python versions, which may define additional names beginning with + one of these prefixes. The header files are typically installed with Python. On Unix, these are located in the directories :file:`{prefix}/include/pythonversion/` and @@ -90,9 +94,11 @@ multi-platform builds since the platform independent headers under :envvar:`prefix` include the platform specific headers from :envvar:`exec_prefix`. -C++ users should note that though the API is defined entirely using C, the -header files do properly declare the entry points to be ``extern "C"``, so there -is no need to do anything special to use the API from C++. +.. note:: + + C++ users should note that although the API is defined entirely using C, the + header files properly declare the entry points to be ``extern "C"``. As a result, + there is no need to do anything special to use the API from C++. Useful macros From 5924d1dbfd81ed601bb296b973ef81e523ee86cf Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Wed, 10 Jul 2019 23:48:30 -0400 Subject: [PATCH 2/4] Remove trailing whitespace On line 74, was causing tests to fail --- Doc/c-api/intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 3db0b81b498968..cba7e22e286ae6 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -71,7 +71,7 @@ standard headers) have one of the prefixes ``Py`` or ``_Py``. Names beginning with ``_Py`` are for internal use by the Python implementation and should not be used by extension writers. Structure member names do not have a reserved prefix. -.. important:: +.. important:: User code should never define names that begin with ``Py`` or ``_Py``. This confuses the reader, and jeopardizes the portability of the user From 5997dd1695081186effb0a0ef6d45110a39a6f3a Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Tue, 10 Sep 2019 07:31:54 -0400 Subject: [PATCH 3/4] Apply suggestions --- Doc/c-api/intro.rst | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index cba7e22e286ae6..627e7a18c55847 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -46,9 +46,7 @@ Include Files ============= All function, type and macro definitions needed to use the Python/C API are -included in your code by the following line: - -.. code:: c +included in your code by the following line:: #define PY_SSIZE_T_CLEAN #include @@ -71,7 +69,7 @@ standard headers) have one of the prefixes ``Py`` or ``_Py``. Names beginning with ``_Py`` are for internal use by the Python implementation and should not be used by extension writers. Structure member names do not have a reserved prefix. -.. important:: +.. note:: User code should never define names that begin with ``Py`` or ``_Py``. This confuses the reader, and jeopardizes the portability of the user @@ -94,11 +92,9 @@ multi-platform builds since the platform independent headers under :envvar:`prefix` include the platform specific headers from :envvar:`exec_prefix`. -.. note:: - - C++ users should note that although the API is defined entirely using C, the - header files properly declare the entry points to be ``extern "C"``. As a result, - there is no need to do anything special to use the API from C++. +C++ users should note that although the API is defined entirely using C, the +header files properly declare the entry points to be ``extern "C"``. As a result, +there is no need to do anything special to use the API from C++. Useful macros From e378f3e0a58dba93a29da1573c4be6204223da89 Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Tue, 10 Sep 2019 10:00:07 -0400 Subject: [PATCH 4/4] Fix words per line --- Doc/c-api/intro.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 627e7a18c55847..80eebd89ad3f25 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -71,10 +71,10 @@ used by extension writers. Structure member names do not have a reserved prefix. .. note:: - User code should never define names that begin with ``Py`` or - ``_Py``. This confuses the reader, and jeopardizes the portability of the user - code to future Python versions, which may define additional names beginning with - one of these prefixes. + User code should never define names that begin with ``Py`` or ``_Py``. This + confuses the reader, and jeopardizes the portability of the user code to + future Python versions, which may define additional names beginning with one + of these prefixes. The header files are typically installed with Python. On Unix, these are located in the directories :file:`{prefix}/include/pythonversion/` and