Add missing edits up to page 98.

Author: paulross

doc/sphinx/source/files.rst

@@ -7,14 +7,37 @@
 .. index::
  single: File Paths and Files
 
+..
+ Links, mostly to the Python documentation.
+ Specific container links are just before the appropriate section.
+
+.. _PyUnicode_FSConverter(): https://docs.python.org/3/c-api/unicode.html#c.PyUnicode_FSConverter
+.. _PyUnicode_FSDecoder(): https://docs.python.org/3/c-api/unicode.html#c.PyUnicode_FSDecoder
+.. _PyUnicode_DecodeFSDefaultAndSize(): https://docs.python.org/3/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize
+.. _PyUnicode_DecodeFSDefault(): https://docs.python.org/3/c-api/unicode.html#c.PyUnicode_DecodeFSDefault
+.. _PyUnicode_EncodeFSDefault(): https://docs.python.org/3/c-api/unicode.html#c.PyUnicode_EncodeFSDefault
+
+.. _PyArg_ParseTupleAndKeywords(): https://docs.python.org/3/c-api/arg.html#c.PyArg_ParseTupleAndKeywords
+
 **********************
 File Paths and Files
 **********************
 
-This chapter describes reading and writing files from C extensions.
+This chapter describes reading and writing files from CPython extensions.
 
 .. index::
  single: File Paths
+ single: File Path Codecs; PyUnicode_FSConverter()
+ single: File Path Codecs; PyUnicode_FSDecoder()
+ single: File Path Codecs; PyUnicode_DecodeFSDefaultAndSize()
+ single: File Path Codecs; PyUnicode_DecodeFSDefault()
+ single: File Path Codecs; PyUnicode_EncodeFSDefault()
+ single: PyUnicode_FSConverter()
+ single: PyUnicode_FSDecoder()
+ single: PyUnicode_DecodeFSDefaultAndSize()
+ single: PyUnicode_DecodeFSDefault()
+ single: PyUnicode_EncodeFSDefault()
+
 
 ====================================
 File Paths
@@ -28,14 +51,18 @@ see also `File Objects <https://docs.python.org/3/c-api/file.html>`_
 
 In summary:
 
-- ``PyUnicode_FSConverter`` Converts a Python a ``str`` or *path-like* object to a Python ``bytes`` object.
-- ``PyUnicode_FSDecoder`` Converts a Python ``bytes`` object to a Python ``str``.
-- ``PyUnicode_DecodeFSDefaultAndSize`` Takes a C string and length and returns a Python ``str``.
-- ``PyUnicode_DecodeFSDefault`` Takes a null terminated C string and length and returns a Python ``str``.
-- ``PyUnicode_EncodeFSDefault`` Takes a Python ``str`` and return a Python ``bytes`` object.
+- `PyUnicode_FSConverter()`_ Converts a Python a ``str`` or *path-like* object to a Python ``bytes`` object.
+- `PyUnicode_FSDecoder()`_ Converts a Python ``bytes`` object to a Python ``str``.
+- `PyUnicode_DecodeFSDefaultAndSize()`_ Takes a C string and length and returns a Python ``str``.
+- `PyUnicode_DecodeFSDefault()`_ Takes a null terminated C string and length and returns a Python ``str``.
+- `PyUnicode_EncodeFSDefault()`_ Takes a Python ``str`` and return a Python ``bytes`` object.
+
+The example code is in:
+- ``src/cpy/cFile.cpp``
+- ``src/cpy/PythonFileWrapper.h``
+- ``src/cpy/PythonFileWrapper.cpp``
 
-The example code is in ``src/cpy/cFile.cpp``, ``src/cpy/PythonFileWrapper.h`` and
-``src/cpy/PythonFileWrapper.cpp`` and the tests are in ``tests/unit/test_c_file.py``.
+The Python tests are in ``tests/unit/test_c_file.py``.
 
 .. index::
  single: File Paths; Parsing Arguments
@@ -46,15 +73,13 @@ Parsing File Paths as Arguments
 
 The Python API provides functionality for converting Python file paths (a ``str`` or *path-like* object)
 to C file paths (``char *``).
-From Python to C;
-`PyUnicode_FSConverter <https://docs.python.org/3/c-api/unicode.html#c.PyUnicode_FSConverter>`_
-and the reverse from C to Python
-`PyUnicode_DecodeFSDefaultAndSize <https://docs.python.org/3/c-api/unicode.html#c.PyUnicode_DecodeFSDefaultAndSize>`_
+From Python to C; `PyUnicode_FSConverter()`_
+and the reverse from C to Python `PyUnicode_DecodeFSDefaultAndSize()`_
 
 Here is an example of taking a Python Unicode string representing a file path, converting it to C and then back
 to Python. The stages are:
 
-- Use ``PyArg_ParseTupleAndKeywords`` and ``PyUnicode_FSConverter`` to convert the path-like Python object to
+- Use `PyArg_ParseTupleAndKeywords()`_ and `PyUnicode_FSConverter()`_ to convert the path-like Python object to
  a Python ``bytes`` object. Note the use of the ``"O&"`` formatting string that takes a Python object and a
  conversion function.
 - Extract the raws bytes to use as a C path.
@@ -80,7 +105,6 @@ Here is the C code:
 
  /* Parse arguments */
  static char *kwlist[] = {"path", NULL};
- /* Can be optional output path with "|O&". */
  if (!PyArg_ParseTupleAndKeywords(args, kwargs, "O&", kwlist, PyUnicode_FSConverter,
  &py_path)) {
  goto except;

doc/sphinx/source/parsing_arguments.rst

@@ -4,6 +4,11 @@
 .. toctree::
  :maxdepth: 3
 
+.. Links to the Python documentation
+
+.. _PyArg_ParseTuple(): https://docs.python.org/3/c-api/arg.html#c.PyArg_ParseTuple
+.. _PyArg_ParseTupleAndKeywords(): https://docs.python.org/3/c-api/arg.html#c.PyArg_ParseTupleAndKeywords
+
 .. index::
  single: Parsing Arguments
 
@@ -133,8 +138,7 @@ Parsing the Arguments
 ------------------------------
 
 Once whe have the C function correctly declared then the arguments have to parsed according to their types.
-This is done using the `PyArg_ParseTuple <https://docs.python.org/3/c-api/arg.html#c.PyArg_ParseTuple>`_
-and `PyArg_ParseTupleAndKeywords <https://docs.python.org/3/c-api/arg.html#c.PyArg_ParseTupleAndKeywords>`_
+This is done using the `PyArg_ParseTuple()`_ and `PyArg_ParseTupleAndKeywords()`_
 (ignoring “old-style” functions which use `PyArg_Parse <https://docs.python.org/3/c-api/arg.html#c.PyArg_Parse>`_).
 
 These use formatting strings that can become bewilderingly complex so this tutorial uses examples as an introduction.
@@ -237,8 +241,6 @@ There is no parsing required here, a single ``PyObject`` is expected:
  Py_RETURN_NONE;
  }
 
-
-
 This function can be added to the module with the ``METH_O`` flag:
 
 .. code-block:: c
@@ -449,7 +451,7 @@ Keyword Arguments and C++11
 
 C++11 compilers warn when creating non-const ``char*`` from string literals as we have done with the keyword array
 above.
-The solution is to declare these ``const char*`` however ``PyArg_ParseTupleAndKeywords`` expects a ``char **``.
+The solution is to declare these ``const char*`` however `PyArg_ParseTupleAndKeywords()`_ expects a ``char **``.
 The solution is to cast away const in the call:
 
 .. code-block:: c
@@ -560,11 +562,11 @@ Suppose we want the functional equivalent of the Python function signature
 
 This is achieved by combining two techniques:
 
-- Positional only: The strings in the ``*kwlist`` passed to ``PyArg_ParseTupleAndKeywords`` are empty.
-- Keyword only: The formatting string passed to ``PyArg_ParseTupleAndKeywords`` uses the ``'$'`` character.
+- Positional only: The strings in the ``*kwlist`` passed to `PyArg_ParseTupleAndKeywords()`_ are empty.
+- Keyword only: The formatting string passed to `PyArg_ParseTupleAndKeywords()`_ uses the ``'$'`` character.
 
 A function using either positional only or keyword only arguments must use the flags ``METH_VARARGS | METH_KEYWORDS``
-and uses ``PyArg_ParseTupleAndKeywords``. Currently, all keyword-only arguments must also be optional arguments, so ``'|'`` must always be
+and uses `PyArg_ParseTupleAndKeywords()`_. Currently, all keyword-only arguments must also be optional arguments, so ``'|'`` must always be
 specified before ``'$'`` in the format string.
 
 Here is the C code:
@@ -610,7 +612,7 @@ Parsing Arguments With Functional Conversion to C
 
 Often you want to convert a Python argument to a C value(s) in a way that is not covered by the format strings
 provided by the Python C API. To do this you can provide a special conversion function in C and give it to
-``PyArg_ParseTuple`` or ``PyArg_ParseTupleAndKeywords``.
+`PyArg_ParseTuple()`_ or `PyArg_ParseTupleAndKeywords()`_.
 
 In this example we are expecting the Python argument to be a list of integers and we want the sum of them as
 a C ``long``. First create a C function that takes a Python list, checks it and sums the values.