Docs: Clean up geometry docs

Author: einarf

docs/user_guide/geometry.rst

@@ -1,6 +1,17 @@
 
+Creating Geometry
+=================
+
+In order to render something to the screen we need geometry as vertex arrays.
+
+We have the following options:
+
+* Using the :py:mod:`demosys.geometry` module (or extend the geometry module)
+* Loading scenes/meshes from file using the supported file formats (or create new loaders of other formats)
+* Generating your own geometry programmatically
+
 The geometry module
-===================
+-------------------
 
 The ``demosys.geometry`` module currently provides some simple
 functions to generate VAOs for simple things.
@@ -12,27 +23,32 @@ Examples:
     from demosys import geometry
     # Create a fullscreen quad for overing the entire screen
     vao = geometry.quad_fs()
+
     # Create a 1 x 1 quad on the xy plane
     vao = geometry.quad_2f(with=1.0, height=1.0)
+
     # Create a unit cube
     vao = geometry.cube(1.0, 1.0, 1.0)
+
     # Create a bounding box
     vao = geometry.bbox()
+
     # Create a sphere
     vao = geometry.sphere(radius=0.5, sectors=32, rings=16)
+
     # Random 10.000 random points in 3d
     vao = geometry.points_random_3d(10_000)
 
 .. Note:: Improvements or suggestions can be made by through pull
    requests or issues on github.
 
-See the ``geometry`` reference for more info.
+See the :py:mod:`demosys.geometry` reference for more info.
 
 Scene/Mesh File Formats
 -----------------------
 
 The ``demosys.scene.loaders`` currently support loading
-wavefront obj files and gltf.
+wavefront obj files and gltf 2.0 files.
 
 You can create your own scene loader by adding the loader
 class to ``SCENE_LOADERS``.
@@ -49,8 +65,13 @@ Generating Custom Geometry
 
 To efficiently generate geometry in Python we must avoid as much memory
 allocation as possible. If performance doesn't matter, then take this
-section lightly. Lbraries like ``numpy`` can also be used to generate
-geometry.
+section lightly.
+
+There are many lbraries out there such as ``numpy`` capable of generating
+geometry fairly efficiently. Here we mainly focus on creating it ourselves
+using pure python code. We're also using the :py:class:`demosys.opengl.vao.VAO`
+for vertex buffer construction. This can easily be translated into using
+``moderngl.VertexArray`` directly if needed.
 
 The naive way of generating geometry would probably look something like this:
 
@@ -75,8 +96,7 @@ The naive way of generating geometry would probably look something like this:
 
 This works perfectly fine, but we allocate a new list for every iteration
 and pyrr internally creates a numpy array. The ``points`` list will also
-have to dynamically expand. This gets exponentially more ugly as the ``count``
-value increases.
+have to dynamically expand. This gets more ugly as the ``count`` value increases.
 
 We move on to version 2:
 
@@ -94,7 +114,7 @@ We move on to version 2:
 
      points_data = numpy.array(points, dtype=numpy.float32)
 
-This version is orders of magnitude faster because we don't allocate memory
+This version is at least and order of magnitude faster because we don't allocate memory
 in the loop. It has one glaring flaw. It's **not a very pleasant read**
 even for such simple task, and it will not get any better if we add more complexity.
 
@@ -114,7 +134,7 @@ Let's move on to version 3:
 
 Using generators in Python like this is much a cleaner way. We also take
 advantage of numpy's ``fromiter()`` that basically slurps up all the
-numbers we emit with yield into its internal buffers. By also telling
+numbers we yield into its internal buffers. By also telling
 numpy what the final size of the buffer will be using the ``count``
 parameter, it will pre-allocate this not having to dynamically increase
 its internal buffer.