Merge pull request #2992 from TTNAN/docs/adj-close-note-860

docs: explain default price adjustment and Close vs Adj Close (fixes #860)

Author: ValueRaider

README.md

@@ -45,6 +45,9 @@
 - `Sector` and `Industry`: sector and industry information
 - `EquityQuery` and `Screener`: build query to screen market
 
+> [!NOTE]
+> [Prices are default adjusted for dividends (`auto_adjust=True`)](https://ranaroussi.github.io/yfinance/advanced/price_adjustment.html).
+
 ## Installation
 
 Install `yfinance` from PYPI using `pip`:

doc/source/advanced/index.rst

@@ -10,4 +10,5 @@ Advanced
    config
    caching
    multi_level_columns
-   price_repair
+   price_repair
+   price_adjustment

doc/source/advanced/price_adjustment.rst

@@ -0,0 +1,12 @@
+****************
+Price adjustment
+****************
+
+By default, ``Ticker.history()`` and ``yf.download()`` return prices **adjusted for splits and dividends** (``auto_adjust=True``). This means the ``Close`` column is already the *adjusted* close — there is no separate ``Adj Close`` column in this mode.
+
+Pass ``auto_adjust=False`` to get Yahoo's split-adjusted OHLC together with an ``Adj Close`` column that also includes dividends.
+
+In other words:
+
+- ``auto_adjust=True`` (default): ``Open``, ``High``, ``Low`` and ``Close`` are all adjusted for splits *and* dividends — the prices you want for total-return-consistent calculations such as backtesting.
+- ``auto_adjust=False``: Yahoo's OHLC as returned (already split-adjusted) plus an ``Adj Close`` column that additionally accounts for dividends.