doc improvements

Author: viblo

CHANGELOG.rst

@@ -1,4 +1,4 @@
-Copyright (c) 2007-2019 Victor Blomqvist
+Copyright (c) 2007-2020 Victor Blomqvist
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

LICENSE.txt

@@ -25,7 +25,7 @@ using Chipmunk 7 rev 080c51480f018040b567e8f0440b121ae3acbae4 .
 Installation
 ------------
 
-In the normal case pymunk can be installed with pip::
+In the normal case pymunk can be installed from PyPI with pip::
 
     > pip install pymunk
 
@@ -86,7 +86,7 @@ It is (or is striving to be):
 
 * **Easy to use** - It should be easy to use, no complicated code should be 
   needed to add physics to your game or program.
-* **"Pythonic"** - It should not be visible that a c-library (chipmunk) is in 
+* **"Pythonic"** - It should not be visible that a c-library (Chipmunk) is in 
   the bottom, it should feel like a Python library (no strange naming, OO, 
   no memory handling and more)
 * **Simple to build & install** - You shouldn't need to have a zillion of 
@@ -116,8 +116,7 @@ Contact & Support
     https://github.com/viblo/pymunk/issues
 
 Regardless of the method you use I will try to answer your questions as soon 
-as I see them. (And if you ask on SO or the forum other people might help as 
-well!)
+as I see them. (And if you ask on SO other people might help as well!)
 
 
 Dependencies / Requirements
@@ -131,7 +130,8 @@ possible, usually `pip install` will take care of everything for you.
 - CFFI (will be installed automatically by Pip)
 - Setuptools (should be included with Pip)
 
-* GCC and friends (optional, you need it to compile Pymunk from source)
+* GCC and friends (optional, you need it to compile Pymunk from source. On 
+  windows Visual Studio is required to compile)
 * Pygame (optional, you need it to run the Pygame based demos)
 * Pyglet (optional, you need it to run the Pyglet based demos)
 * Matplotlib & Jupyter Notebook (optional, you need it to run the Matplotlib 

README.rst

@@ -7,8 +7,8 @@ want a better understanding of Pymunk for example to extend it.
 
 First off, Pymunk is a pythonic wrapper around the C-library Chipmunk. 
 
-To wrap Chipmunk Pymunk uses CFFI. On top of the CFFI wrapping is a handmade 
-pythonic layer to make it nice to use from Python code.
+To wrap Chipmunk Pymunk uses CFFI in API mode. On top of the CFFI wrapping is
+a handmade pythonic layer to make it nice to use from Python code.
 
 Why CFFI?
 ---------
@@ -23,7 +23,7 @@ Advantages (compared to ctypes):
 * Its an active project. The developers and users are active, there are new 
   releases being made and its possible to ask and get answers within a day on 
   the CFFI mailing list.
-* Its said to be the way forward for pypy, with promise of better performance 
+* Its said to be the way forward for Pypy, with promise of better performance 
   compares to ctypes.
 * A little easier than ctypes to wrap things since you can just copy-paste the 
   c headers.
@@ -125,13 +125,11 @@ Code Layout
 Most of Pymunk should be quite straight forward.
 
 Except for the documented API Pymunk has a couple of interesting parts. Low 
-level bindings to Chipmunk, a custom library load function, a custom 
-documentation generation extension and a customized setup.py file to allow
-compilation of Chipmunk.
+level bindings to Chipmunk, a custom documentation generation extension and a
+customized setup.py file to allow compilation of Chipmunk.
 
-The low level chipmunk bindings are located in the two files _chipmunk_cffi.py 
-and _chipmunk_cffi_abi.py. In order to locate and load the compiled chipmunk 
-library file pymunk uses a custom load_library function in _libload.py
+The low level chipmunk bindings are located in the file 
+pymunk_extension_build.py. 
 
 docs/src/ext/autoexample.py
     A Sphinx extension that scans a directory and extracts the toplevel 
@@ -147,15 +145,11 @@ pymunk/_chipmkunk_cffi_abi.py
     This file contains the pure Cffi wrapping definitons. Bascially a giant 
     string created by copy-paster from the relevant header files of Chipmunk.  
 
-pymunk/_libload.py
-    This file contains the custom Cffi library load function that is used 
-    by the rest of pymunk to load the Chipmunk library file.
-
 setup.py
     Except for the standard setup stuff this file also contain the custom 
     build commands to build Chipmunk from source, using a build_ext extension.
 
-tests/*
+pymunk/tests/*
     Collection of (unit) tests. Does not cover all cases, but most core 
     things are there. The tests require a working chipmunk library file.
 
@@ -180,7 +174,14 @@ argument. The matching is as broad as possible, so `UnitTest` matches all the
 unit tests, `test_arbiter` all tests in `test_arbiter.py` and 
 `testResetitution` matches the exact `testRestitution` test case ::
 
-    > python -m pymunk.tests testRestitution
+    > python -m pymunk.tests -f testRestitution
+
+To see all options to the tests command use -h ::
+
+    > python -m pymunk.tests -h
+
+Since the tests cover even the optional parts, you either have to make sure 
+all the optional dependencies are installed, or filter out those tests.
 
 
 Working with non-wrapped parts of Chipmunk
@@ -194,7 +195,7 @@ wrapped by pymunk. The Chipmunk method to get this property is named
 cpBodyIsSleeping.
 
 First we need to check if its included in the cdef definition in 
-_chipmunk_cffi.abi.py. If its not just add it.
+pymunk_extension_build.py. If its not just add it.
 
     `cpBool cpBodyIsSleeping(const cpBody *body);`
 
@@ -206,20 +207,13 @@ Then to make it easy to use we want to create a python method that looks nice::
 Now we are ready with the mapping and ready to use our new method.
 
 
-Weak References and __del__ Methods
+Weak References and free Methods
 -----------------------------------
 
 Internally Pymunk allocates structs from Chipmunk (the c library). For example a 
 Body struct is created from inside the constructor method when a pymunk.Body is 
-created. Because of this several Pymunk objects uses a __del__() method that 
-cleans up the underlying c struct when the object is deleted. 
-
-Use of a __del__() method prevents the normal CPython GC (garbage collection) 
-from handling cyclic references since it wont know in which order to run the 
-__del__() methods. Some Pymunk objects naturally keeps cyclic references to each 
-other to make them easier to use. One such example is the body and shape object. 
-A shape is attached to a body, and a body has a set of all shapes that has been 
-attached. To make it easier for the user of the library these cyclic references 
-have been broken up so that the reference in one direction is weak and dont 
-affect GC. Usually the user do not need to worry about this, but in the cases a 
-reference is weak it is marked in the API documentation of the specific method.
+created. Because of this its important that the corresponding c side memory is 
+deallocated properly when not needed anymore, usually when the Python side 
+object is garbage collected. Most Pymunk objects use `ffi.gc` with a custom 
+free function to do this. Note that the order of freeing is very important to 
+avoid errors.

docs/src/advanced.rst

@@ -1,5 +1,6 @@
 Benchmarks
 ==========
+.. _benchmark:
 
 To get a grip of the actual performance of Pymunk this page contains a number
 of benchmarks.  
@@ -111,7 +112,7 @@ callback test using the collision handler::
 
     s.step(0.01)
 
-(see `pymunk-collision-callback.py and  `cymunk-collision-callback.py`)
+(see `pymunk-collision-callback.py` and  `cymunk-collision-callback.py`)
 
 Results
 +++++++

docs/src/benchmarks.rst

@@ -0,0 +1 @@
+.. include:: ../../CHANGELOG.rst

docs/src/changelog.rst

@@ -56,11 +56,6 @@ Given that pymunk is installed where your python will find it::
 
     >cd examples
     >python breakout.py
-
-To run directly without installing anything. From the pymunk source folder::
-
-    >cd examples
-    >python run.py breakout.py 
     
 Each example contains something unique. Not all of the examples use the same 
 style. For example, some use the pymunk.pygame_util module to draw stuff, 

docs/src/examples.rst

@@ -6,7 +6,7 @@ Contents
 .. toctree::
     :maxdepth: 4
 
-    news
+    changelog
     installation
     overview
     pymunk
@@ -15,9 +15,9 @@ Contents
     tutorials
     benchmarks
     advanced
+    Downloads <https://pypi.python.org/pypi/pymunk/>
     Issue Tracker <https://github.com/viblo/pymunk/issues>
     Source Repository <https://github.com/viblo/pymunk>
-    Downloads <https://pypi.python.org/pypi/pymunk/>
     license
 
 Indices and tables

docs/src/index.rst

@@ -22,7 +22,7 @@ Pymunk can also be installed with conda install, from the conda-forge channel::
 Once Pymunk is installed you can verify that the installation works by running 
 the tests::
 
-    > python -m pymunk.tests test
+    > python -m pymunk.tests -f test
 
 Sometimes on more uncommon platforms you will need to have a GCC-compatible 
 c-compiler installed. 
@@ -40,7 +40,7 @@ with::
 Examples & Documentation
 ========================
 
-Because of their size are the examples and documentation available in the 
+Because of their size the examples and the documentation are available in the 
 source distribution of Pymunk, but not the wheels. The source distribution is 
 available from PyPI at https://pypi.org/project/pymunk/#files (Named
 pymunk-x.y.z.zip)
@@ -147,10 +147,6 @@ the path::
     sys.path.insert(1, 'pymunk')
     import pymunk
 
-The same trick can be used to import pymunk for a script that is not in the 
-direct parent folder, see for example `run.py` in the examples which update 
-the path to simplify development.
-
 
 .. _compile-chipmunk:
 
@@ -174,9 +170,7 @@ place in the source folder::
 
     > python setup.py build_ext --inplace
 
-On Windows you will need to use a gcc-compatible compiler. The pre-built version
-distributed with pymunk were compiled with the MinGW-w64 GCC compiler at 
-https://www.msys2.org/
+On Windows you will need to use Visual Studio matching your Python version. 
 
 .. seealso::