Merge pull request #171 from skuschel/ku/doc

documentation updates

Updates a lot of docstings, Readme, links to the postpic-examples repository.
Sphinx theme and sphinx autodoc.

Most of #138

.github/issue_template.md

@@ -0,0 +1,13 @@
+
+Please tell us which version of postpic you are using by adding the output of
+```python
+import postpic as pp
+print(pp.__version__)
+```
+Please also add if you are using python2 or python3. You can find out using
+```python
+import sys
+print(sys.version)
+```
+
+Now continue with your question or bug report here. Thank you!

.gitignore

@@ -1,5 +1,6 @@
 # auto generated by setup.py
-examples/_openPMDdata
+/examples/_openPMDdata
+/_examplepictures
 
 # Byte-compiled / optimized / DLL files
 __pycache__/
@@ -14,18 +15,18 @@ __pycache__/
 
 # Distribution / packaging
 .Python
-env/
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
+/env/
+/build/
+/develop-eggs/
+/dist/
+/downloads/
+/eggs/
+/.eggs/
+/lib/
+/lib64/
+/parts/
+/sdist/
+/var/
 *.egg-info/
 .installed.cfg
 *.egg
@@ -56,7 +57,7 @@ coverage.xml
 *.log
 
 # Sphinx documentation
-doc/_build/
+/doc/build/
 
 # PyBuilder
 target/

CONTRIBUTING.md

@@ -1,8 +1,8 @@
 
-Contributing to the PostPic code base
+Contributing to the postpic code base
 =====================================
 
-Any help contributing to the PostPic project ist greatly appreciated! Feel free to contact any of the developers or ask for help using the [Issues](https://github.com/skuschel/postpic/issues) Page.
+Any help contributing to the postpic project ist greatly appreciated! Feel free to contact any of the developers or ask for help using the [Issues](https://github.com/skuschel/postpic/issues) Page.
 
 Why me?
 -------
@@ -15,13 +15,13 @@ How to contribute?
 
 Reporting bugs or asking questions works with a GitHub account simply on the [Issues](https://github.com/skuschel/postpic/issues) page.
 
-For any coding you need to be familiar with [git](http://git-scm.com/). Its a distributed version control system created by Linus Torvalds (and more importantly: he is also using it for maintaining the linux kernel). There is a nice introduction to git at [try.github.io/](http://try.github.io/), but in general you can follow the bootcamp section at [https://help.github.com/](https://help.github.com/) for your first steps. 
+For any coding you need to be familiar with [git](http://git-scm.com/). Its a distributed version control system created by Linus Torvalds (and more importantly: he is also using it for maintaining the linux kernel). There is a nice introduction to git at [try.github.io/](http://try.github.io/), but in general you can follow the bootcamp section at [https://help.github.com/](https://help.github.com/) for your first steps.
 
 One of the most comprehensive guides is probably [this book](http://git-scm.com/doc). Just start reading from the beginning. It is worth it!
 
 ## The Workflow
 
-Adding a feature is often triggered by the personal demand for it. Thats why production ready features should propagte to master as fast as possible. Everything on master is considered to be production ready. We follow the  [github-flow](http://scottchacon.com/2011/08/31/github-flow.html) describing this very nicely. 
+Adding a feature is often triggered by the personal demand for it. Thats why production ready features should propagte to master as fast as possible. Everything on master is considered to be production ready. We follow the  [github-flow](http://scottchacon.com/2011/08/31/github-flow.html) describing this very nicely.
 
 In short:
 
@@ -30,15 +30,15 @@ In short:
   0. Create a branch whose name tells what you do. Something like `codexy-reader` or `fixwhatever`,... is a good choice. Do NOT call it `issue42`. Git history should be clearly readable without external information. If its somehow unspecific in the worst case call it `dev` or even commit onto your `master` branch.
   0. Implement a new feature/bugfix/documentation/whatever commit to your local repository. It is highly recommended that the new features will have test cases.
   0. KEEP YOUR FORK UP TO DATE! Your fork is yours, only. So you have to update it to whatever happens in the main repository. To do so add the main repository as a second remote with
-  
+
    `git remote add upstream [email protected]:skuschel/postpic.git`
 
    and pull from it regularly with
 
   `git pull --rebase upstream master`
-  
+
   0. Make sure all tests are running smoothly (the `run-tests.py` script also involves pep8 style verification!) Run `run-tests.py` before EVERY commit!
-  0. push to your fork and create a [pull request](https://help.github.com/articles/using-pull-requests/) EARLY! Even if your feature or fix is not yet finished, create the pull request and start it with `WIP:` or `[WIP]` (work-in-progress) to show its not yet ready to merge in. But the pull request will 
+  0. push to your fork and create a [pull request](https://help.github.com/articles/using-pull-requests/) EARLY! Even if your feature or fix is not yet finished, create the pull request and start it with `WIP:` or `[WIP]` (work-in-progress) to show its not yet ready to merge in. But the pull request will
     * trigger travis.ci to run the tests whenever you push
     * show other people what you work on
     * ensure early feedback on your work

README.md

@@ -1,22 +1,29 @@
 postpic
 =======
+
 [![Build Status](https://travis-ci.org/skuschel/postpic.svg?branch=master)](https://travis-ci.org/skuschel/postpic)
 [![PyPI version](https://badge.fury.io/py/postpic.png)](http://badge.fury.io/py/postpic)
 [![Documentation Status](https://readthedocs.org/projects/postpic/badge/?version=latest)](https://postpic.readthedocs.org/)
 
-postpic is a open-source post processor for Particle-in-cell (PIC) simulations written in python.  If you are doing PIC Simulations (likely for you PhD in physics...) you need tools to provide proper post-processing to create nice graphics from many GB of raw simulation output data -- regardless of what simulation code you are using.
+Postpic is a open-source post processor for Particle-in-cell (PIC) simulations written in python. If you are doing PIC Simulations (likely for you PhD in physics...) you need tools to provide proper post-processing to create nice graphics from many GB of raw simulation output data -- regardless of what simulation code you are using.
+
+**For working examples, please go to  https://github.com/skuschel/postpic-examples**
+
+The (technical, but complete) documentation is hosted on
+https://postpic.readthedocs.io/en/latest/
 
 
 Idea of postpic
 ---------------
 
-The basic idea of postpic is to calculate the plots you are interested in just from the basic data the Simulation provides. This data includes electric and magnetic fields and a tuple (weight, x, y, z, px, py, pz) for every macro-particle. Anything else you want to look at (for example a spectrum at your detector) should just be calculated from these values. This is exactly what postpic can do for you, and even more:
+The basic idea of postpic is to calculate the plots you are interested in just from the basic data the simulation provides. This data includes electric and magnetic fields and a tuple (`weight`, `x`, `y`, `z`, `px`, `py`, `pz`, `id`, `mass`, `charge`, `time`) for every macro-particle. Anything else you like to look at (for example a spectrum at your detector) should just be calculated from these values. This is exactly what postpic can do for you, and even more:
 
 postpic has a unified interface for reading the required simulation data. If the simulation code of your choice is not supported by postic, this is the perfect opportunity to add a new datareader.
 
 Additionally postpic can plot and label your plot automatically. This makes it easy to work with and avoids mistakes. Currently matplotlib is used for that but this is also extensible.
 
 
+
 Installation
 ------------
 

doc/source/apidoc/postpic.io.rst

@@ -0,0 +1,44 @@
+postpic\.io package
+===================
+
+.. automodule:: postpic.io
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Submodules
+----------
+
+postpic\.io\.common module
+--------------------------
+
+.. automodule:: postpic.io.common
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+postpic\.io\.csv module
+-----------------------
+
+.. automodule:: postpic.io.csv
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+postpic\.io\.npy module
+-----------------------
+
+.. automodule:: postpic.io.npy
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+postpic\.io\.vtk module
+-----------------------
+
+.. automodule:: postpic.io.vtk
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+

doc/source/apidoc/postpic.rst

@@ -12,6 +12,7 @@ Subpackages
 .. toctree::
 
     postpic.datareader
+    postpic.io
     postpic.particles
     postpic.plotting
 
@@ -42,12 +43,4 @@ postpic\.helper module
     :undoc-members:
     :show-inheritance:
 
-postpic\.io module
-------------------
-
-.. automodule:: postpic.io
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 

doc/source/conf.py

@@ -123,7 +123,14 @@ def setup(app):
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    'github_user': 'skuschel',
+    'github_repo': 'postpic',
+    'github_banner': True,  # fork me on github banner
+    'github_button': True,
+    'description': 'the open source partice-in-cell postprocessor.',
+    'page_width': '1000px',
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -137,8 +144,10 @@ def setup(app):
 # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
 html_sidebars = {
     '**': [
+        'about.html',
+        'navigation.html',
         'relations.html',  # needs 'show_related': True theme option to display
-        'localtoc.html',
+        #'localtoc.html',
         'sourcelink.html',
         'searchbox.html',
     ]

doc/source/introduction.rst

@@ -3,7 +3,9 @@
 Introduction
 ============
 
-*The open-source particle-in-cell postprocessor.*
+.. automodule:: postpic
+  :no-members:
+
 
 
 What is postpic?
@@ -14,7 +16,6 @@ Postpic is an open-source package aiming to ease the postprocessing of particle-
 
 .. automodule:: postpic.datareader
 
-
 .. autofunction:: postpic.readDump
 
 .. autofunction:: postpic.readSim

postpic/__init__.py

@@ -20,7 +20,33 @@
 |   POSTPIC    |
 +--------------+
 
-The open source particle-in-cell post processor.
+  *The open source particle-in-cell post processor.*
+
+Particle-in-cell simulations are a valuable tool for the simulation of non-equelibrium
+systems in plasma- or astrophysics.
+Such simulations usually produce a large amount of data consisting of electric and magnetic
+field data as well as particle positions and momenta. While there are various PIC codes freely
+available, the task of post-processing -- essentially condensing the large amounts of data
+into small units suitable for plotting routines -- is typically left to each user individually.
+As post-processing may be a time consuming and error-prone process,
+this python package has been developed.
+
+*Postpic* can handle two different types of data:
+
+Field data
+  which is data sampled on a predefined grid, such as electic and magnetic fields, particle- or
+  charge densities, currents, etc.
+  Fields are usually the data, which can be plotted directly.
+  See :class:`postpic.Field`.
+
+Particle data
+  which is data of multiple particles and for each particle positions (`x`, `y`, `z`) and
+  momenta (`px`, `py`, `pz`) are known. Particles usually also have `weight`,
+  `charge`, `time` and a unique `id`.
+  Postpic can transform particle data to field data using the same algorithm and particle shapes,
+  which are used in most PIC Simulations. The particle-to-grid routines are written in C
+  for maximum performance. See :class:`postpic.MultiSpecies`.
+
 """
 from __future__ import absolute_import, division, print_function, unicode_literals
 

postpic/datahandling.py

@@ -28,16 +28,19 @@ class -- the final output of the postpic postprocessor.
 A data field with N numeric points has N 'grid' points,
 but N+1 'grid_nodes' as depicted here:
 
-+---+---+---+---+---+
-|   |   |   |   |   |
-+---+---+---+---+---+
-|   |   |   |   |   |
-+---+---+---+---+---+
-|   |   |   |   |   |
-+---+---+---+---+---+
-  o   o   o   o   o     grid      (coordinates where data is sampled at)
-o   o   o   o   o   o   grid_node (coordinates of grid cell boundaries)
-|                   |   extent
+.. code-block:: none
+
+  +---+---+---+---+---+
+  |   |   |   |   |   |
+  +---+---+---+---+---+
+  |   |   |   |   |   |
+  +---+---+---+---+---+
+  |   |   |   |   |   |
+  +---+---+---+---+---+
+    o   o   o   o   o     grid      (coordinates where data is sampled at)
+  o   o   o   o   o   o   grid_node (coordinates of grid cell boundaries)
+  |                   |   extent
+
 """
 from __future__ import absolute_import, division, print_function, unicode_literals