Merge pull request #2120 from ValueRaider/dev-documented

Improve Sphinx docs
ranaroussi · Nov 16, 2024 · a9e70b4 · a9e70b4
2 parents 5d8b444 + ce8f8a0
commit a9e70b4
Show file tree

Hide file tree

Showing 23 changed files with 311 additions and 202 deletions.
diff --git a/doc/source/_templates/autosummary/class.rst b/doc/source/_templates/autosummary/class.rst
@@ -1,4 +1,6 @@
-{{ fullname | escape | underline}}
+:orphan:
+
+{{ objname | escape | underline }}
 
 .. currentmodule:: {{ module }}
 
@@ -7,24 +9,21 @@
    {% block attributes %}
    {% if attributes %}
    .. rubric:: Attributes
-
-   .. autosummary::
-      :toctree: attributes
+
    {% for item in attributes %}
-      ~{{ name }}.{{ item }}
+   .. autoattribute:: {{ item }}
+      :noindex:
    {%- endfor %}
    {% endif %}
-   {% endblock %}
-
+   {% endblock attributes %}
 
    {% block methods %}
    {% if methods %}
    .. rubric:: Methods
 
-   .. autosummary::
-      :toctree: methods
    {% for item in methods %}
-      ~{{ name }}.{{ item }}
+   .. automethod:: {{ item }}
+      :noindex:
    {%- endfor %}
    {% endif %}
-   {% endblock %}
+   {% endblock methods %}
diff --git a/doc/source/user_guide/smart_scraping.rst → doc/source/advanced/caching.rst b/doc/source/user_guide/smart_scraping.rst → doc/source/advanced/caching.rst
@@ -1,7 +1,8 @@
-******************************
-Smarter Scraping with Caching
-******************************
+Caching
+=======
 
+Smarter Scraping
+----------------
 
 Install the `nospam` package to cache API calls and reduce spam to Yahoo:
 
@@ -39,3 +40,20 @@ Combine `requests_cache` with rate-limiting to avoid triggering Yahoo's rate-lim
       bucket_class=MemoryQueueBucket,
       backend=SQLiteCache("yfinance.cache"),
    )
+
+
+Persistent Cache
+----------------
+
+To reduce Yahoo, yfinance store some data locally: timezones to localize dates, and cookie. Cache location is:
+
+- Windows = C:/Users/\<USER\>/AppData/Local/py-yfinance
+- Linux = /home/\<USER\>/.cache/py-yfinance
+- MacOS = /Users/\<USER\>/Library/Caches/py-yfinance
+
+You can direct cache to use a different location with :attr:`set_tz_cache_location <yfinance.set_tz_cache_location>`:
+
+.. code-block:: python
+
+    import yfinance as yf
+    yf.set_tz_cache_location("custom/cache/location")
diff --git a/doc/source/advanced/index.rst b/doc/source/advanced/index.rst
@@ -0,0 +1,11 @@
+========
+Advanced
+========
+
+.. toctree::
+   :maxdepth: 2
+
+   logging
+   proxy
+   caching
+   multi_level_columns
diff --git a/doc/source/user_guide/logging.rst → doc/source/advanced/logging.rst b/doc/source/user_guide/logging.rst → doc/source/advanced/logging.rst
@@ -1,5 +1,5 @@
-Logging in yfinance
-===================
+Logging
+=======
 
 `yfinance` uses the `logging` module to handle messages. By default, only errors are logged.
 

diff --git a/...source/user_guide/multi_level_columns.rst → doc/source/advanced/multi_level_columns.rst b/...source/user_guide/multi_level_columns.rst → doc/source/advanced/multi_level_columns.rst
@@ -1,6 +1,6 @@
-******************************
-Managing Multi-Level Columns
-******************************
+************************
+Multi-Level Column Index
+************************
 
 The following answer on Stack Overflow is for `How to deal with
 multi-level column names downloaded with yfinance? <https://stackoverflow.com/questions/63107801>`_

diff --git a/doc/source/user_guide/proxy.rst → doc/source/advanced/proxy.rst b/doc/source/user_guide/proxy.rst → doc/source/advanced/proxy.rst
@@ -1,6 +1,6 @@
-*********************
-Using a Proxy Server
-*********************
+************
+Proxy Server
+************
 
 You can download data via a proxy:
 

diff --git a/doc/source/development/index.rst b/doc/source/development/index.rst
@@ -1,5 +1,6 @@
+===========
 Development
-===============================
+===========
 
 .. toctree::
    :maxdepth: 1

diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst
diff --git a/doc/source/getting_started/installation.rst b/doc/source/getting_started/installation.rst
diff --git a/doc/source/getting_started/legal.rst b/doc/source/getting_started/legal.rst
diff --git a/doc/source/getting_started/quick_start.rst b/doc/source/getting_started/quick_start.rst
diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -1,8 +1,8 @@
 yfinance documentation
-==============================================
+======================
 
 Download Market Data from Yahoo! Finance's API
-------------------------------------------------
+----------------------------------------------
 
 .. admonition:: IMPORTANT LEGAL DISCLAIMER
 
@@ -19,12 +19,56 @@ Download Market Data from Yahoo! Finance's API
    for details on your rights to use the actual data downloaded.
    Remember - the Yahoo! finance API is intended for personal use only.
 
+Install
+-------
+
+.. code-block:: bash
+
+    $ pip install yfinance
+
+Quick start
+-----------
+
+Showing a small sample of yfinance API, the full API is much bigger and covered in :doc:`reference/index`.
+
+.. code-block:: python
+
+   import yfinance as yf
+   dat = yf.Ticker("MSFT")
+
+
+One ticker symbol
+
+.. code-block:: python
+
+   dat = yf.Ticker("MSFT")
+   dat.info
+   dat.calendar
+   dat.analyst_price_targets
+   dat.quarterly_income_stmt
+   dat.history(period='1mo')
+   dat.option_chain(dat.options[0]).calls
+
+Multiple ticker symbols
+
+.. code-block:: python
+
+   tickers = yf.Tickers('MSFT AAPL GOOG')
+   tickers.tickers['MSFT'].info
+   yf.download(['MSFT', 'AAPL', 'GOOG'], period='1mo')
+
+Funds
+
+.. code-block:: python
+
+   spy = yf.Ticker('SPY').funds_data
+   spy.description
+   spy.top_holdings
+
 .. toctree::
-   :maxdepth: 3
-   :hidden:
+   :maxdepth: 1
    :titlesonly:
 
-   getting_started/index
-   user_guide/index
+   advanced/index
    reference/index
    development/index
diff --git a/doc/source/reference/examples/ticker.py b/doc/source/reference/examples/ticker.py
@@ -1,77 +1,22 @@
 import yfinance as yf
 
-msft = yf.Ticker("MSFT")
-
-# get all stock info
-msft.info
+dat = yf.Ticker("MSFT")
 
 # get historical market data
-hist = msft.history(period="1mo")
-
-# show meta information about the history (requires history() to be called first)
-msft.history_metadata
-
-# show actions (dividends, splits, capital gains)
-msft.actions
-msft.dividends
-msft.splits
-msft.capital_gains  # only for mutual funds & etfs
-
-# show share count
-msft.get_shares_full(start="2022-01-01", end=None)
-
-# show financials:
-msft.calendar
-msft.sec_filings
-# - income statement
-msft.income_stmt
-msft.quarterly_income_stmt
-# - balance sheet
-msft.balance_sheet
-msft.quarterly_balance_sheet
-# - cash flow statement
-msft.cashflow
-msft.quarterly_cashflow
-# see `Ticker.get_income_stmt()` for more options
-
-# show holders
-msft.major_holders
-msft.institutional_holders
-msft.mutualfund_holders
-msft.insider_transactions
-msft.insider_purchases
-msft.insider_roster_holders
-
-msft.sustainability
-
-# show recommendations
-msft.recommendations
-msft.recommendations_summary
-msft.upgrades_downgrades
-
-# show analysts data
-msft.analyst_price_targets
-msft.earnings_estimate
-msft.revenue_estimate
-msft.earnings_history
-msft.eps_trend
-msft.eps_revisions
-msft.growth_estimates
+dat.history(period='1mo')
 
-# Show future and historic earnings dates, returns at most next 4 quarters and last 8 quarters by default.
-# Note: If more are needed use msft.get_earnings_dates(limit=XX) with increased limit argument.
-msft.earnings_dates
+# options
+dat.option_chain(dat.options[0]).calls
 
-# show ISIN code - *experimental*
-# ISIN = International Securities Identification Number
-msft.isin
+# get financials
+dat.balance_sheet
+dat.quarterly_income_stmt
 
-# show options expirations
-msft.options
+# dates
+dat.calendar
 
-# show news
-msft.news
+# general info
+dat.info
 
-# get option chain for specific expiration
-opt = msft.option_chain('YYYY-MM-DD')
-# data available via: opt.calls, opt.puts
+# analysis
+dat.analyst_price_targets
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
@@ -1,6 +1,6 @@
-=======================
+=============
 API Reference
-=======================
+=============
 
 Overview
 --------
@@ -27,7 +27,13 @@ The following are the publicly available classes, and functions exposed by the `
    :maxdepth: 1
    :hidden:
 
-   
+
    yfinance.ticker_tickers
+   yfinance.stock
+   yfinance.financials
+   yfinance.analysis
    yfinance.sector_industry
-   yfinance.functions
+   yfinance.functions
+
+   yfinance.funds_data
+   yfinance.price_history