Update all of the documentation headers.

HexDecimal · HexDecimal · commit 1ef9d0ea16fb · 2020-06-24T14:37:45.000-07:00
Also some other doc updates, mostly to the glossary.
diff --git a/docs/glossary.rst b/docs/glossary.rst
@@ -14,22 +14,29 @@ Glossary
         This is the `cffi` implementation of libtcodpy, the original was
         made using `ctypes` which was more difficult to maintain.
 
-        `libtcod-cffi` is now part of :term:`python-tcod`.
+        `libtcod-cffi` has since been part of :term:`python-tcod` providing
+        all of the :term:`libtcodpy` API until the newer features could be
+        implemented.
 
     python-tcod
         `python-tcod` is a superset of the :term:`libtcodpy` API.  The major
         additions include class functionality in returned objects, no manual
         memory management, pickle-able objects, and `numpy` array attributes
         in most objects.
 
-        The `numpy` attributes in particular can be used to dramatically speed
-        up the performance of your program compared to using :term:`libtcodpy`.
+        The `numpy` functions in particular can be used to dramatically speed
+        up the performance of a program compared to using :term:`libtcodpy`.
 
     python-tdl
         `tdl` is a high-level wrapper over :term:`libtcodpy` although it now
         uses :term:`python-tcod`, it doesn't do anything that you couldn't do
         yourself with just :term:`libtcodpy` and Python.
 
+        It included a lot of core functions written in Python that most
+        definitely shouldn't have been.  `tdl` was very to use, but the cost
+        was severe performance issues throughout the entire module.
+        This left it impractical for any real use as a roguelike library.
+
         Currently no new features are planned for `tdl`, instead new features
         are added to `libtcod` itself and then ported to :term:`python-tcod`.
 
@@ -38,8 +45,9 @@ Glossary
 
     libtcodpy
         `libtcodpy` is more or less a direct port of `libtcod`'s C API to
-        Python.  This caused a handful of issues including instances needing
-        to be freed manually or a memory leak will occur, and some functions
+        Python.
+        This caused a handful of issues including instances needing to be
+        freed manually or else a memory leak would occur, and many functions
         performing badly in Python due to the need to call them frequently.
 
         These issues are fixed in :term:`python-tcod` which implements the full
diff --git a/docs/libtcodpy.rst b/docs/libtcodpy.rst
@@ -1,5 +1,15 @@
-libtcodpy
-=========
+libtcodpy - Old API Functions
+=============================
+
+This is all the functions included since the start of the Python port.
+This collection is often called :term:`libtcodpy`, the name of the original
+Python port.  These functions are reproduced by python-tcod in their entirely.
+
+**A large majority of these functions are deprecated and will be removed in
+the future.
+In general this entire section should be avoided whenever possible.**
+See :ref:`getting-started` for how to make a new python-tcod project with its
+modern API.
 
 bsp
 ---
diff --git a/docs/tcod/bsp.rst b/docs/tcod/bsp.rst
@@ -1,5 +1,5 @@
-tcod.bsp
-=========
+tcod.bsp - Binary Space Partitioning
+====================================
 
 .. automodule:: tcod.bsp
     :members:
diff --git a/docs/tcod/console.rst b/docs/tcod/console.rst
@@ -1,5 +1,5 @@
-tcod.console
-============
+tcod.console - Tile Drawing/Printing
+====================================
 
 .. automodule:: tcod.console
     :members:
diff --git a/docs/tcod/context.rst b/docs/tcod/context.rst
@@ -1,5 +1,5 @@
-tcod.context
-============
+tcod.context - Window Management
+================================
 
 .. automodule:: tcod.context
     :members:
diff --git a/docs/tcod/event.rst b/docs/tcod/event.rst
@@ -1,5 +1,5 @@
-tcod.event
-==========
+tcod.event - SDL2 Event Handling
+================================
 
 .. automodule:: tcod.event
     :members:
diff --git a/docs/tcod/image.rst b/docs/tcod/image.rst
@@ -1,5 +1,5 @@
-tcod.image
-==========
+tcod.image - Image Handling
+===========================
 
 .. automodule:: tcod.image
     :members:
diff --git a/docs/tcod/los.rst b/docs/tcod/los.rst
@@ -1,5 +1,5 @@
-tcod.los
-========
+tcod.los - Line of Sight
+========================
 
 .. automodule:: tcod.los
     :members:
diff --git a/docs/tcod/map.rst b/docs/tcod/map.rst
@@ -1,5 +1,5 @@
-tcod.map
-========
+tcod.map - Field of View
+========================
 
 .. automodule:: tcod.map
     :members:
diff --git a/docs/tcod/noise.rst b/docs/tcod/noise.rst
@@ -1,5 +1,5 @@
-tcod.noise
-==========
+tcod.noise - Noise Map Generators
+=================================
 
 .. automodule:: tcod.noise
     :members:
diff --git a/docs/tcod/path.rst b/docs/tcod/path.rst
@@ -1,5 +1,5 @@
-tcod.path
-=========
+tcod.path - Pathfinding
+=======================
 
 .. automodule:: tcod.path
     :members:
diff --git a/docs/tcod/random.rst b/docs/tcod/random.rst
@@ -1,5 +1,5 @@
-tcod.random
-===========
+tcod.random - Random Number Generators
+======================================
 
 .. automodule:: tcod.random
     :members:
diff --git a/docs/tcod/tileset.rst b/docs/tcod/tileset.rst
@@ -1,5 +1,5 @@
-tcod.tileset
-============
+tcod.tileset - Font Loading Functions
+=====================================
 
 .. automodule:: tcod.tileset
     :members:
diff --git a/tcod/image.py b/tcod/image.py
@@ -1,3 +1,12 @@
+"""Functionality for handling images.
+
+**Python-tcod is unable to render pixels to the screen directly.**
+If your image can't be represented as tiles then you'll need to use
+`an alternative library for graphics rendering
+<https://wiki.python.org/moin/PythonGameLibraries>`_.
+"""
+
+
 from typing import Any, Dict, Tuple
 
 import numpy as np
diff --git a/tcod/noise.py b/tcod/noise.py
@@ -1,8 +1,7 @@
-"""
-The :any:`Noise.sample_mgrid` and :any:`Noise.sample_ogrid` methods are
-multi-threaded operations when the Python runtime supports OpenMP.
-Even when single threaded these methods will perform much better than
-multiple calls to :any:`Noise.get_point`.
+"""Noise map generators are provided by this module.
+
+The :any:`Noise.sample_mgrid` and :any:`Noise.sample_ogrid` methods perform
+much better than multiple calls to :any:`Noise.get_point`.
 
 Example::
 
diff --git a/tcod/path.py b/tcod/path.py
@@ -1,4 +1,4 @@
-"""
+"""This module provides a fast configurable pathfinding implementation.
 
 Example::
 
diff --git a/tcod/tileset.py b/tcod/tileset.py
@@ -1,4 +1,14 @@
 """Tileset and font related functions.
+
+Tilesets can be loaded as a whole from tile-sheets or True-Type fonts, or they
+can be put together from multiple tile images by loading them separately
+using :any:`Tileset.set_tile`.
+
+A major restriction with libtcod is that all tiles must be the same size and
+tiles can't overlap when rendered.  For sprite-based rendering it can be
+useful to use `an alternative library for graphics rendering
+<https://wiki.python.org/moin/PythonGameLibraries>`_ while continuing to use
+python-tcod's pathfinding and field-of-view algorithms.
 """
 import os
 
diff --git a/tdl/__init__.py b/tdl/__init__.py
@@ -1,6 +1,8 @@
 """
     .. deprecated:: 8.4
-        This module has been deprecated.
+        The :term:`python-tdl` module has been a total disaster and now exists
+        mainly as a historical curiosity and as a stepping stone for what would
+        eventually become :term:`python-tcod`.
 
     Getting Started
     ===============
