DOC: Update docs and examples

Author: kernc

backtesting/backtesting.py

@@ -1,6 +1,6 @@
 """
-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
@@ -909,7 +909,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.
         """
@@ -1093,7 +1093,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,
@@ -1283,7 +1283,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

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.3.5
 #   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).

doc/examples/Multiple Time Frames.py

@@ -6,7 +6,7 @@
 #       extension: .py
 #       format_name: light
 #       format_version: '1.5'
-#       jupytext_version: 1.3.0
+#       jupytext_version: 1.3.5
 #   kernelspec:
 #     display_name: Python 3
 #     language: python
@@ -21,10 +21,9 @@
 # [basic _backtesting.py_ usage](https://kernc.github.io/backtesting.py/doc/examples/Quick Start User Guide.html).
 #
 # First, let's again import our helper moving average function.
-# In practice, one can use functions from any indicator library, such as
-# [TA-Lib](https://github.com/mrjbq7/ta-lib),
-# [Tulipy](https://tulipindicators.org),
-# PyAlgoTrade, ...
+# 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).
 
 from backtesting.test import SMA
 
@@ -33,7 +32,7 @@
 # but we will use four moving averages in total:
 # two moving averages whose relationship determines a general trend
 # (we only trade long when the shorter MA is above the longer one, and vice versa),
-# and two moving averages whose cross-over with Close prices determine the signal to enter or exit the position.
+# and two moving averages whose cross-over with daily _close_ prices determine the signal to enter or exit the position.
 
 # +
 from backtesting import Strategy
@@ -121,7 +120,7 @@ def next(self):
 
 heatmap.sort_values().iloc[-3:]
 
-# But people have this enormous faculty of vision, used to make judgements on much larger data sets much faster.
+# But we use vision to make judgements on larger data sets much faster.
 # Let's plot the whole heatmap by projecting it on two chosen dimensions.
 # Say we're mostly interested in how parameters `n1` and `n2`, on average, affect the outcome.
 
@@ -152,3 +151,9 @@ def next(self):
 
 
 plot_heatmaps(heatmap, agg='mean')
+# -
+
+# 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).