DOC: Update docs and examples

Author: kernc

backtesting/__init__.py

@@ -1,6 +1,11 @@
 """
 # Backtesting.py Documentation
 
+.. warning:: v0.2.0 breaking changes
+   Version 0.2.0 introduced some **breaking API changes**. For quick ways to
+   migrate existing 0.1.x code, see the implementing
+   [pull request](https://github.com/kernc/backtesting.py/pull/47/).
+
 ## Manuals
 
 * [**Quick Start User Guide**](../examples/Quick Start User Guide.html)
@@ -11,7 +16,7 @@
 * [Multiple Time Frames](../examples/Multiple Time Frames.html)
 * [Parameter Heatmap](../examples/Parameter Heatmap.html)
 
-These tutorials are also available as live notebooks:
+These tutorials are also available to test as live Jupyter notebooks:
 [![Binder](https://mybinder.org/badge_logo.svg)][binder]
 
 [binder]: \
@@ -22,6 +27,11 @@
 
 * (contributions welcome)
 
+## FAQ
+
+Potentially outdated answers to popular questions can be found on the
+[issue tracker](https://github.com/kernc/backtesting.py/issues?q=label%3Aquestion).
+
 ## License
 
 This software is licensed under the terms of [AGPL 3.0]{: rel=license},

backtesting/backtesting.py

@@ -1,9 +1,14 @@
 """
-Core backtesting data structures.
-Objects from this module can be imported from the top-level
+Core framework data structures.
+Objects from this module can also be imported from the top-level
 module directly, e.g.
 
     from backtesting import Backtest, Strategy
+
+.. warning:: v0.2.0 breaking changes
+   Version 0.2.0 introduced some **breaking API changes**. For quick ways to
+   migrate existing 0.1.x code, see the implementing
+   [pull request](https://github.com/kernc/backtesting.py/pull/47/).
 """
 import multiprocessing as mp
 import os
@@ -962,7 +967,7 @@ def __init__(self,
         To run the backtest using e.g. 50:1 leverge that your broker allows,
         set margin to `0.02` (1 / leverage).
 
-        If `trade_on_close` is `True`, market orders will be executed
+        If `trade_on_close` is `True`, market orders will be filled
         with respect to the current bar's closing price instead of the
         next bar's open.
 
@@ -1029,6 +1034,37 @@ def run(self, **kwargs) -> pd.Series:
         Run the backtest. Returns `pd.Series` with results and statistics.
 
         Keyword arguments are interpreted as strategy parameters.
+
+            >>> Backtest(GOOG, SmaCross).run()
+            Start                     2004-08-19 00:00:00
+            End                       2013-03-01 00:00:00
+            Duration                   3116 days 00:00:00
+            Exposure Time [%]                     93.9944
+            Equity Final [$]                      51959.9
+            Equity Peak [$]                       75787.4
+            Return [%]                            419.599
+            Buy & Hold Return [%]                 703.458
+            Max. Drawdown [%]                    -47.9801
+            Avg. Drawdown [%]                    -5.92585
+            Max. Drawdown Duration      584 days 00:00:00
+            Avg. Drawdown Duration       41 days 00:00:00
+            # Trades                                   65
+            Win Rate [%]                          46.1538
+            Best Trade [%]                         53.596
+            Worst Trade [%]                      -18.3989
+            Avg. Trade [%]                        2.35371
+            Max. Trade Duration         183 days 00:00:00
+            Avg. Trade Duration          46 days 00:00:00
+            Profit Factor                         2.08802
+            Expectancy [%]                        8.79171
+            SQN                                  0.916893
+            Sharpe Ratio                         0.179141
+            Sortino Ratio                         0.55887
+            Calmar Ratio                         0.049056
+            _strategy                            SmaCross
+            _equity_curve                           Eq...
+            _trades                       Size  EntryB...
+            dtype: object
         """
         data = _Data(self._data.copy(deep=False))
         broker = self._broker(data=data)  # type: _Broker
@@ -1160,7 +1196,7 @@ def __getattr__(self, item):
             raise ValueError('No admissible parameter combinations to test')
 
         if len(param_combos) > 300:
-            warnings.warn('Searching best of {} configurations.'.format(len(param_combos)),
+            warnings.warn('Searching for best of {} configurations.'.format(len(param_combos)),
                           stacklevel=2)
 
         heatmap = pd.Series(np.nan,
@@ -1367,7 +1403,7 @@ def plot(self, *, results: pd.Series = None, filename=None, plot_width=None,
         a separate drawdown graph section.
 
         If `smooth_equity` is `True`, the equity graph will be
-        interpolated between points of cash-only positions,
+        interpolated between fixed points at trade closing times,
         unaffected by any interim asset volatility.
 
         If `relative_equity` is `True`, scale and label equity graph axis

backtesting/lib.py

@@ -175,7 +175,7 @@ def resample_apply(rule: str,
     a time frame to resample `series` to.
 
     [Pandas offset string]: \
-        http://pandas.pydata.org/pandas-docs/stable/timeseries.html#offset-aliases
+http://pandas.pydata.org/pandas-docs/stable/timeseries.html#offset-aliases
 
     `func` is the indicator function to apply on the resampled series.
 
@@ -202,7 +202,7 @@ def init(self):
                 self.sma = resample_apply(
                     'D', SMA, self.data.Close, 10, plot=False)
 
-    This short snippet is roughly equivalent to:
+    The above short snippet is roughly equivalent to:
 
         class System(Strategy):
             def init(self):

doc/examples/Multiple Time Frames.ipynb

@@ -5,7 +5,7 @@
 #       extension: .py
 #       format_name: light
 #       format_version: '1.5'
-#       jupytext_version: 1.3.0
+#       jupytext_version: 1.5.1
 #   kernelspec:
 #     display_name: Python 3
 #     language: python
@@ -16,22 +16,21 @@
 # ============
 #
 # The best trading strategies relying on technical analysis take into account the price action on multiple time frames.
-# This tutorial will show how to do that with _backtesting.py_, offloading most of the work to
+# This tutorial will show how to do that with backtesting.py, offloading most of the work to
 # [pandas resampling](http://pandas.pydata.org/pandas-docs/stable/timeseries.html#resampling).
 # It is assumed you're already familiar with
-# [basic _backtesting.py_ usage](https://kernc.github.io/backtesting.py/doc/examples/Quick Start User Guide.html).
+# [basic usage](https://kernc.github.io/backtesting.py/doc/examples/Quick Start User Guide.html).
 #
 # We will put to the test this long-only, supposed
 # [400%-a-year trading strategy](http://jbmarwood.com/stock-trading-strategy-300/),
 # which uses daily and weekly
 # [relative strength index](https://en.wikipedia.org/wiki/Relative_strength_index)
 # (RSI) values and moving averages (MA).
 #
-# Let's introduce the two indicators we'll be using.
-# In practice, one can use functions from any indicator library, such as
-# [TA-Lib](https://github.com/mrjbq7/ta-lib),
+# In practice, one should use functions from an indicator library, such as
+# [TA-Lib](https://github.com/mrjbq7/ta-lib) or
 # [Tulipy](https://tulipindicators.org),
-# PyAlgoTrade, ...
+# but among us, let's introduce the two indicators we'll be using.
 
 # +
 import pandas as pd
@@ -138,5 +137,10 @@ def next(self):
 
 # Better. While the strategy doesn't perform as well as simple buy & hold, it does so with significantly lower exposure (time in market).
 #
-# In conclusion, to test strategies on multiple time frames, you need to pass in data in the lowest time frame, then resample it to higher time frames, apply the indicators, then resample back to the lower time frame, filling in the in-betweens.
+# In conclusion, to test strategies on multiple time frames, you need to pass in OHLC data in the lowest time frame, then resample it to higher time frames, apply the indicators, then resample back to the lower time frame, filling in the in-betweens.
 # Which is what the function [`backtesting.lib.resample_apply()`](https://kernc.github.io/backtesting.py/doc/backtesting/lib.html#backtesting.lib.resample_apply) does for you.
+
+# Learn more by exploring further
+# [examples](https://kernc.github.io/backtesting.py/doc/backtesting/index.html#tutorials)
+# or find more framework options in the
+# [full API reference](https://kernc.github.io/backtesting.py/doc/backtesting/index.html#header-submodules).