Update documentation structure, add links to migration page

docs/deprecated.md

@@ -48,12 +48,10 @@ As this does however increase risk and provides no benefit, it's been removed fo
 Using separate hyperopt files was deprecated in 2021.4 and was removed in 2021.9.
 Please switch to the new [Parametrized Strategies](hyperopt.md) to benefit from the new hyperopt interface.
 
-## Margin / short changes
-
-// TODO-lev: update version here
-
 ## Strategy changes between V2 and V3
 
+Isolated Futures / short trading was introduced in 2022.4. This required major changes to configuration settings, strategy interfaces, ...
+
 We have put a great effort into keeping compatibility with existing strategies, so if you just want to continue using freqtrade in spot markets, there are no changes necessary.
 While we may drop support for the current interface sometime in the future, we will announce this separately and have an appropriate transition period.
 

docs/faq.md

@@ -8,6 +8,7 @@ Freqtrade supports spot trading only.
 
 Freqtrade can open short positions in futures markets.
 This requires the strategy to be made for this - and `"trading_mode": "futures"` in the configuration.
+Please make sure to read the [relevant documentation page](leverage.md) first.
 
 In spot markets, you can in some cases use leveraged spot tokens, which reflect an inverted pair (eg. BTCUP/USD, BTCDOWN/USD, ETHBULL/USD, ETHBEAR/USD,...) which can be traded with Freqtrade.
 

docs/leverage.md

@@ -1,4 +1,4 @@
-# Leverage
+# Trading with Leverage
 
 !!! Warning "Beta feature"
     This feature is still in it's testing phase. Should you notice something you think is wrong please let us know via Discord or via Github Issue.
@@ -7,7 +7,7 @@
     You can't run 2 bots on the same account with leverage. For leveraged / margin trading, freqtrade assumes it's the only user of the account, and all liquidation levels are calculated based on this assumption.
 
 !!! Danger "Trading with leverage is very risky"
-    Do not trade with a leverage > 1 using a strategy that hasn't shown positive results in a live run using the spot market. Check the stoploss of your strategy. With a leverage of 2, a stoploss of 0.5 would be too low, and these trades would be liquidated before reaching that stoploss.
+    Do not trade with a leverage > 1 using a strategy that hasn't shown positive results in a live run using the spot market. Check the stoploss of your strategy. With a leverage of 2, a stoploss of 0.5 (50%) would be too low, and these trades would be liquidated before reaching that stoploss.
     We do not assume any responsibility for eventual losses that occur from using this software or this mode.
 
     Please only use advanced trading modes when you know how freqtrade (and your strategy) works.

docs/strategy_migration.md

@@ -1,35 +1,37 @@
 # Strategy Migration between V2 and V3
 
-We have put a great effort into keeping compatibility with existing strategies, so if you just want to continue using freqtrade in spot markets, there should be no changes necessary for now.
-
 To support new markets and trade-types (namely short trades / trades with leverage), some things had to change in the interface.
 If you intend on using markets other than spot markets, please migrate your strategy to the new format.
 
+We have put a great effort into keeping compatibility with existing strategies, so if you just want to continue using freqtrade in __spot markets__, there should be no changes necessary for now.
+
+You can use the quick summary as checklist. Please refer to the detailed sections below for full migration details.
+
 ## Quick summary / migration checklist
 
 * Strategy methods:
-  * `populate_buy_trend()` -> `populate_entry_trend()`
+  * [`populate_buy_trend()` -> `populate_entry_trend()`](#populate_buy_trend)
-  * `populate_sell_trend()` -> `populate_exit_trend()`
+  * [`populate_sell_trend()` -> `populate_exit_trend()`](#populate_sell_trend)
-  * `custom_sell()` -> `custom_exit()`
+  * [`custom_sell()` -> `custom_exit()`](#custom_sell)
-  * `check_buy_timeout()` -> `check_entry_timeout()`
+  * [`check_buy_timeout()` -> `check_entry_timeout()`](#custom_entry_timeout)
-  * `check_sell_timeout()` -> `check_exit_timeout()`
+  * [`check_sell_timeout()` -> `check_exit_timeout()`](#custom_entry_timeout)
+  * New `side` argument to callbacks without trade object
+    * [`custom_stake_amount`](#custom-stake-amount)
+    * [`confirm_trade_entry`](#confirm_trade_entry)
+  * [Changed argument name in `confirm_trade_exit`](#confirm_trade_exit)
 * Dataframe columns:
-  * `buy` -> `enter_long`
+  * [`buy` -> `enter_long`](#populate_buy_trend)
-  * `sell` -> `exit_long`
+  * [`sell` -> `exit_long`](#populate_sell_trend)
-  * `buy_tag` -> `enter_tag` (used for both long and short trades)
+  * [`buy_tag` -> `enter_tag` (used for both long and short trades)](#populate_buy_trend)
-  * New column `enter_short` and corresponding new column `exit_short`
+  * [New column `enter_short` and corresponding new column `exit_short`](#populate_sell_trend)
 * trade-object now has the following new properties: `is_short`, `enter_side`, `exit_side` and `trade_direction`.
-* New `side` argument to callbacks without trade object
+* [Renamed `trade.nr_of_successful_buys` to `trade.nr_of_successful_entries` (mostly relevant for `adjust_trade_position()`)](#adjust-trade-position-changes)
-  * `custom_stake_amount`
-  * `confirm_trade_entry`
-* Changed argument name in `confirm_trade_exit`
-* Renamed `trade.nr_of_successful_buys` to `trade.nr_of_successful_entries` (mostly relevant for `adjust_trade_position()`).
 * Introduced new [`leverage` callback](strategy-callbacks.md#leverage-callback).
 * Informative pairs can now pass a 3rd element in the Tuple, defining the candle type.
 * `@informative` decorator now takes an optional `candle_type` argument.
-* helper methods `stoploss_from_open` and `stoploss_from_absolute` now take `is_short` as additional argument.
+* [helper methods](#helper-methods) `stoploss_from_open` and `stoploss_from_absolute` now take `is_short` as additional argument.
 * `INTERFACE_VERSION` should be set to 3.
-* Strategy/Configuration settings.
+* [Strategy/Configuration settings](#strategyconfiguration-settings).
   * `order_time_in_force` buy -> entry, sell -> exit.
   * `order_types` buy -> entry, sell -> exit.
   * `unfilledtimeout` buy -> entry, sell -> exit.
@@ -339,7 +341,7 @@ unfilledtimeout = {
 Order pricing changed in 2 ways. `bid_strategy` was renamed to `entry_strategy` and `ask_strategy` was renamed to `exit_strategy`.
 The attributes `ask_last_balance` -> `price_last_balance` and `bid_last_balance` -> `price_last_balance` were renamed as well.
 Also, price-side can now be defined as `ask`, `bid`, `same` or `other`.
-Please refer to the [pricing documentation](configuration.md) for more information.
+Please refer to the [pricing documentation](configuration.md#prices-used-for-orders) for more information.
 
 ``` json hl_lines="2-3 6 12-13 16"
 {

mkdocs.yml

@@ -22,8 +22,7 @@ nav:
     - Data Downloading: data-download.md
     - Backtesting: backtesting.md
     - Hyperopt: hyperopt.md
-    - Leverage: leverage.md
+    - Short / Leverage: leverage.md
-    - Strategy migration: strategy_migration.md
     - Utility Sub-commands: utils.md
     - Plotting: plotting.md
     - Exchange-specific Notes: exchanges.md
@@ -38,6 +37,7 @@ nav:
         - Sandbox Testing: sandbox-testing.md
     - FAQ: faq.md
     - SQL Cheat-sheet: sql_cheatsheet.md
+    - Strategy migration: strategy_migration.md
     - Updating Freqtrade: updating.md
     - Deprecated Features: deprecated.md
     - Contributors Guide: developer.md