Misc. docs cleanup

Author: a-hurst

doc/faq.rst

@@ -2,23 +2,24 @@
 
 PySDL2 FAQ
 ==========
-This is a list of Frequently Asked Questions about PySDL2. If you think,
-something is missing, please suggest it!
+This is a list of Frequently Asked Questions about PySDL2. If there are any
+questions and answers you would like added here, please let us know on GitHub!
 
 On importing...
 ---------------
 ... my script fails and complains that a SDL2 library could not be found!
 
-   Do you have the libraries properly installed? If on macOS or Windows, 
-   try running ``pip install pysdl2-dll`` and opening a fresh terminal
-   to fix the problem. If on Linux or similar, did you follow the operating
-   system's way of installing or registering libraries? If you placed the
-   libraries in some folder, make sure that the ``PYSDL2_DLL_PATH``
-   environment variable points to the correct location.
+   Do you have the libraries properly installed? On most platforms, you can
+   install them easily using ``pip install pysdl2-dll``. On ARM64 macOS, you
+   can install native SDL2 binaries using the Homebrew package manager. For
+   BSD, Linux on exotic architectures (not x86 or ARM64), and other Unix-like
+   platforms, install the SDL2 binaries using your system's package manager. On
+   all platforms, you can manually set the path of your SDL2 binaries using
+   the ``PYSDL2_DLL_PATH`` environment variable.
 
 ... my script fails complaining that the *found* SDL2 library can't be used!
 
-   Do you use a 64-bit operating system? Please make sure, that the Python
+   Do you use a 64-bit operating system? Please make sure that the Python
    interpreter *and* that the SDL2 libraries are either 64-bit ones *or*
    32-bit ones. A 32-bit Python interpreter can't deal with a 64-bit library
    and vice versa.
@@ -28,28 +29,34 @@ Using...
 
 ... the sdl2 API is weird. Why do you use the SDL\_ prefix all the time?
 
-   The low-level APIs for SDL2, SDL2\_mixer, SDL2\_ttf, ... shall represent a 
-   clean wrapping around the original C API calls. Thus, if you have to search
-   for documentation or want to make a Python to C conversion (or C to Python),
-   most of the code cleanly maps to the original API naming and layout and you
-   do not have to think about whether you had to use SDL\_ or TTF\_ or whatever
-   as prefix or suffix.
+   PySDL2 offers 1-to-1 bindings for most of the SDL2 API, keeping the same
+   function names and arguments as the original SDL2, SDL2\_mixer, SDL2\_ttf,
+   SDL2\_image, and SDL2\_gfx libraries. This makes the package much easier to
+   maintain, but also makes it easy to reference the SDL2 documentation and
+   adapt C SDL2 examples into Python code. For a friendlier, more Pythonic
+   wrapper around the SDL2 API, take a look at PySDL2's :mod:`sdl2.ext`
+   module.
 
-... the sdl2 API is does not comply to PEP-8. Please make it PEP-8 compatible.
+... the sdl2 API does not comply to PEP-8. Please make it PEP-8 compatible.
 
-   Most of the API is PEP-8 compatible. The low-level bindings to SDL2 and
-   related libraries however use the exact naming (including capital letters)
-   as the functions or structures, they map to. See the previous entry for
-   the reason of that.
+   Most of the API is PEP-8 compatible. However, the low-level bindings to SDL2
+   and its addon libraries use the exact same function/structure/constant naming
+   as their C counterparts, meaning that PySDL2 will necessarily diverge from
+   PEP-8 in some places. The :mod:`sdl2.ext` module should theoretically be
+   fully PEP-8 compliant.
 
 How do I...
 -----------
 
 ... save my surfaces as image files?
 
-   You can use :func:`sdl2.SDL_SaveBMP()` to save them as bitmap files. Other
-   formats are currently unsupported, but might be added to
-   the :mod:`sdl2.ext` package in the future.
+   You can use :func:`sdl2.ext.save_bmp()` to save them as bitmap files, or the
+   low-level :func:`sdl2.sdlimage.IMG_SavePNG()` function to save them to PNG on
+   systems with SDL\_image installed. For a wider range of formats, you can use
+   the :func:`~sdl2.ext.surface_to_ndarray` function to convert an SDL surface
+   into a Numpy array, open the array with the Pillow library using
+   ``Image.from_array()``, and then save it to any export format supported by
+   Pillow.
 
 
 Font handling...
@@ -59,10 +66,7 @@ Font handling...
 
    The :mod:`sdl2.sdlttf` API does not know about platform-specific font
    locations and is unable to resolve font paths based on e.g. the font name
-   or typeface. It's not its job and PySDL2 likewise does not provide such
-   functionality. If you need improved font detection support, you might want
-   to take a look at the sysfont module of the python-utils project, which can
-   be found at https://bitbucket.org/marcusva/python-utils/. That said, it's
-   usually a bad idea for a projects to rely on system fonts that may not be
-   available on every computer: finding a free-use font you like and bundling
-   it with your code is much safer.
+   or typeface. Additionally, it's usually a bad idea for a projects to rely
+   on system fonts that may not be available on every computer: finding a
+   free-use font you like and bundling it with your project is almost always
+   the better option.

doc/install.rst

@@ -3,16 +3,30 @@ Installing PySDL2
 This section provides an overview and guidance for installing PySDL2 on
 various target platforms.
 
-Getting the sources
--------------------
+Using pip
+---------
+The easiest way to get up and running with PySDL2 is to install it and the
+SDL2 binaries it depends on using the Pip package manager ::
+
+  python -m pip install pysdl2 pysdl2-dll 
+
+Note that the pysdl2-dll binaries may not be available yet for your platform.
+If not, please read through the Prerequisites section below.
+
+Installing from source
+----------------------
 You can download the official releases of PySDL2 from
 https://github.com/marcusva/py-sdl2/releases. Download the most
 recent release, unpack it and make sure that you installed the relevant
 prerequisites before continuing with the installation.
 
+Then, you can install PySDL2 directly with Python ::
+
+   python setup.py install
+
 Prerequisites
 -------------
-PySDL2 relies on some 3rd party packages to be fully usable and to
+PySDL2 relies on some additional libraries to be fully usable and to
 provide you full access to all of its features.
 
 You must have at least one of the following Python versions installed:
@@ -24,38 +38,23 @@ Other Python versions or Python implementations might work, but are
 (currently) not officially tested or supported by the PySDL2
 distribution.
 
-You need to have a working SDL2 library on your target system. You can obtain
-the source code (to build it yourself) or a prebuilt version at
-http://www.libsdl.org. Alternatively, on macOS and Windows, you can install
-the SDL2 binaries for PySDL2 using pip via the pysdl2-dll package.
+You need to have a working SDL2 library on your target system. On Windows
+(32-bit and 64-bit x86), macOS (64-bit x86), and Linux (32-bit/64-bit x86,
+and 64-bit ARM), you can install the latest official binaries with pip via the
+pysdl2-dll package. Alternatively, you can install it using your system's
+package manager, download the official binaries from http://www.libsdl.org, or
+compile it from source yourself.
 
-PySDL2 also offers support for the following SDL-related libraries:
+PySDL2 also offers optional support for the following SDL-related libraries:
 
 * SDL2_image             (http://www.libsdl.org/projects/SDL_image/)
 * SDL2_mixer             (http://www.libsdl.org/projects/SDL_mixer/)
 * SDL2_ttf               (http://www.libsdl.org/projects/SDL_ttf/)
 * SDL2_gfx               (http://www.ferzkopp.net/Software/SDL_gfx-2.0/)
 
-Those are optional though and only necessary if you want to use
-:mod:`sdl2.sdlimage`, :mod:`sdl2.sdlmixer`, :mod:`sdl2.sdlttf` or
-:mod:`sdl2.sdlgfx`.
-
-Installation
-------------
-You can either use the python way of installing the package or the make
-command using the Makefile on POSIX-compatible platforms, such as Linux
-or BSD, or the make.bat batch file on Windows platforms.
-
-Simply type ::
-
-  python setup.py install
-
-for the traditional python way or ::
-
-  make install
-
-for using the Makefile or make.bat. Both will try to perform a default
-installation with as many features as possible.
+However, these are only necessary if you want to use the :mod:`sdl2.sdlimage`,
+:mod:`sdl2.sdlmixer`, :mod:`sdl2.sdlttf` or :mod:`sdl2.sdlgfx` modules. Binaries
+for all these modules are provided by the pysdl2-dll package.
 
 Trying out
 ^^^^^^^^^^

doc/integration.rst

@@ -19,9 +19,9 @@ The :mod:`sdl2` package relies on an external SDL2 library for creating the
 wrapper functions. This means that the user needs to have SDL2 installed or
 that you ship a SDL2 library with your project.
 
-For macOS, Windows, and most distributions of x86 Linux, the easiest and most
-flexible way to bundle and install the SDL2 binaries with your project is via
-the ``pysdl2-dll`` package on PyPI,
+For macOS, Windows, and most distributions of x86 and ARM64 Linux, the easiest
+and most flexible way to bundle and install the SDL2 binaries with your project
+is via the ``pysdl2-dll`` package on PyPI,
 which pysdl2 will load automatically if available. This approach allows you to
 add the SDL2 binaries as a dependency for your project in a requirements.txt
 file, a setup.py file, a Pipfile, or any other form of Python dependency
@@ -30,7 +30,7 @@ project using this mechanism if your project depends on a function not
 available in earlier versions of SDL2.
 
 For platforms without any available pysdl2-dll binaries (e.g. Alpine Linux, 
-ARM64 Linux, BSD), PySDL2 will still work as long as a recent version of SDL2
+ARM32 Linux, BSD), PySDL2 will still work as long as a recent version of SDL2
 is installed using the system's package manager. Additionally, pysdl2-dll will
 still install successfully on unsupported platforms as an empty pacakge with
 no binaries, making it safe to add as a dependency for cross-platform projects.
@@ -53,7 +53,7 @@ be found.
    it will try to use that one in the first place, before using any SDL2
    library installed on the target system.
 
-Let's assume, you ship your own library *SDL2.dll* within your project
+Let's assume you ship your own library *SDL2.dll* within your project
 location *fancy_project/third_party*. You can set the environment
 variable :envvar:`PYSDL2_DLL_PATH` before starting Python. ::
 

doc/news.rst

@@ -78,7 +78,7 @@ Fixed Bugs:
   ``TTF_RenderUTF`` instead of ``TTF_RenderUTF8``.
 * Fixed a bug introduced in 0.9.9 where the ``SDL_WINDOW_INPUT_GRABBED``
   constant was no longer exported.
-* :class:`~sdl2.ext.MemoryView` and :class:`~sdl2.ext.PixelAccess `objects now
+* :class:`~sdl2.ext.MemoryView` and :class:`~sdl2.ext.PixelAccess` objects now
   support negative indexing (e.g. ``arr[-1][-1]`` for accessing the last element
   in a 2D array). In previous versions, negative indices would retrieve values
   from undefined sections of memory outside the surface (PR #204)
@@ -92,8 +92,8 @@ Fixed Bugs:
 * :meth:`sdl2.ext.BitmapFont.contains` no longer assumes that the font map
   contains a space (PR #208)
 * Rendering multiline text with the :class:`sdl2.ext.BitmapFont` class now
-  always splits lines using the newline (`\n`) character. Previously on
-  Windows, it would only split on Windows-style line endings (`\r\n`) (PR #208)
+  always splits lines using the newline (``\n``) character. Previously on
+  Windows, it would only split on Windows-style line endings (``\r\n``) (PR #208)
 
 API Changes:
 
@@ -109,12 +109,12 @@ API Changes:
 * Updated the :meth:`~sdl2.ext.Renderer.draw_line` and
   :meth:`~sdl2.ext.Renderer.draw_point` methods of the
   :class:`~sdl2.ext.Renderer` class to accept coordinates as lists of ``(x, y)``
-  tuples or :obj:`~sdl2.SDL_Point`s in addition to flat ``[x, y, x, y, x, y]``
+  tuples or :obj:`~sdl2.SDL_Point` in addition to flat ``[x, y, x, y, x, y]``
   lists (PR #207)
 * Updated the :meth:`~sdl2.ext.Renderer.draw_rect` and
   :meth:`~sdl2.ext.Renderer.fill` methods of the
   :class:`~sdl2.ext.Renderer` class to accept coordinates as lists of
-  :obj:`~sdl2.SDL_Rects`s in addition to lists of ``(x, y, w, h)``
+  :obj:`~sdl2.SDL_Rect` in addition to lists of ``(x, y, w, h)``
   tuples (PR #207)
 * Updated the :meth:`~sdl2.ext.Renderer.copy` method of the
   :class:`~sdl2.ext.Renderer` class to accept an ``(x, y)`` tuple as a