Updated docs

Author: forman

CHANGES.md

@@ -2,6 +2,9 @@
 
 ### Enhancements
 
+* It is now possible to configure runtime profiling of the `zappend`
+  processing using the new configuration setting `profiling`. [#39]
+
 * Allow for passing custom slice sources via the configuration.
   The new configuration setting `slice_source` is the name of a class 
   derived from `zappend.api.SliceSource` or a function that creates an instance 

docs/config.md

@@ -187,6 +187,41 @@ Type _boolean_.
 If 'true', log only what would have been done, but don't apply any changes.
 Defaults to `false`.
 
+### `profiling`
+
+Profiling configuration. Allows for runtime profiling of the processing.
+Must be one of the following:
+* Type _boolean_.
+  If set, profiling is enabled and output is logged using level INFO. Otherwise, profiling is disabled.
+* Type _string_.
+  Profile path. Enables profiling and writes a profiling report to given path.
+* Type _object_.
+  
+  * `enabled`:
+    Type _boolean_.
+    Enable or disable profiling.
+  * `path`:
+    Type _string_.
+    Local file path for profiling output.
+  * `log_level`:
+    Log level. Use 'NOTSET' to disable logging.
+    Defaults to `"INFO"`.
+    Must be one of `"CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG", "NOTSET"`.
+  * `keys`:
+    Type _array_.
+    Sort output according to the supplied column names. Refer to [Stats.sort_stats(*keys)](https://docs.python.org/3/library/profile.html#pstats.Stats.sort_stats).
+    
+    Must be one of `"calls", "cumulative", "cumtime", "file", "filename", "module", "ncalls", "pcalls", "line", "name", "nfl", "stdname", "time", "tottime"`.
+  * `restrictions`:
+    Type _array_.
+    Used to limit the list down to the significant entries in the profiling report. Refer to [Stats.print_stats(*restrictions)](https://docs.python.org/3/library/profile.html#pstats.Stats.print_stats).
+    
+    Must be one of the following:
+    * Type _integer_.
+    * Type _number_.
+    * Type _string_.
+  
+
 ### `logging`
 
 Type _object_.

docs/guide.md

@@ -618,6 +618,49 @@ zappend(["slice-1.nc", "slice-2.nc", "slice-3.nc"],
         slice_source=MySliceSource)
 ```
 
+## Profiling
+
+Runtime profiling is very important for understanding program runtime behavior 
+and performance. The configuration setting `profiling` can be used to
+analyse and improve the runtime performance of `zappend` itself as well as 
+the runtime performance of the computation of in-memory slices passed to the
+`zappend()` function.
+
+To log the output of the profiling with level `INFO` (see next section 
+[Logging](#logging)), you can use the value `true`:
+
+```json
+{
+    "profiling": true
+}
+```
+
+If you like to see the output in a file too, then set `profiling` to the 
+desired local file path:
+
+```json
+{
+    "profiling": "perf.out"
+}
+```
+
+You can also set `profiling` to an object that allows for fine-grained 
+control of the runtime logging: 
+
+```json
+{
+    "profiling": {
+        "log_level": "WARNING",
+        "path": "perf.out",
+        "keys": ["tottime", "time", "ncalls"]
+    }
+}
+```
+
+Please refer to section [`profiling`](config.md#profiling) in 
+the [Configuration Reference](config.md) for more details.
+
+
 ## Logging
 
 The `zappend` logging output is configured using the `logging` setting.