docs: change sphinx configuration

Jupyter Notebooks from examples can be used in docs
mbk-dev · Sep 15, 2021 · 0b26d9f · 0b26d9f
1 parent 22d2eaa
commit 0b26d9f
Show file tree

Hide file tree

Showing 16 changed files with 427 additions and 313 deletions.
diff --git a/docs/_templates/custom-class-template.rst b/docs/_templates/custom-class-template.rst
@@ -0,0 +1,20 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+    {% block members %}
+    {% if members %}
+    .. rubric:: {{ _('Methods & Attributes') }}
+
+    .. autosummary::
+        :toctree:
+        :caption: Methods & Attributes
+    {% for item in members %}
+        {%- if not item.startswith('_') %}
+        ~{{ name }}.{{ item }}
+        {%- endif -%}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
diff --git a/docs/conf.py b/docs/conf.py
@@ -1,8 +1,5 @@
 # Configuration file for the Sphinx documentation builder.
 #
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 import os
 import sys
@@ -44,14 +41,14 @@
 # The full version, including alpha/beta/rc tags.
 release = version
 
+# -- General configuration ---------------------------------------------------
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 language = "en"
 
-# -- General configuration ---------------------------------------------------
-
-autodoc_default_flags = ["members"]
-autosummary_generate = ["index"]
+# The encoding of source files.
+source_encoding = "utf-8"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -66,6 +63,7 @@
     "sphinx.ext.mathjax",
     "sphinx_rtd_theme",
     "nbsphinx",
+    "nbsphinx_link",
     "recommonmark",
     # "myst_parser",  # for markdown
 ]
@@ -93,12 +91,14 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-# html_theme_options = {
-#     "external_links": [],
-#     # "github_url": "https://github.com/mbk-dev/okama",
-#     # "twitter_url": "https://twitter.com/pandas_dev",
-#     # "google_analytics_id": "UA-27880019-2",
-# }
+html_theme_options = {
+    # "external_links": [],
+    # "github_url": "https://github.com/mbk-dev/okama",
+    # "google_analytics_id": "UA-27880019-2",
+    # Toc options
+    "titles_only": False,
+    "navigation_depth": 4,
+}
 
 # If false, no module index is generated.
 html_use_modindex = False
@@ -110,11 +110,16 @@
 
 # -- Options for autodoc    ------------------------------------------------
 
-# This value controls how to represents typehints.
+autodoc_default_flags = ["members"]
+autodoc_default_options = {
+    'undoc-members': False,
+    'exclude-members': '__init__'}
 autodoc_typehints = "none"
 autodoc_member_order = "bysource"
 autoclass_content = "class"  # to not insert __init__ docstrings
 autodoc_class_signature = "mixed"  # Display the signature with the class name.
+autosummary_generate = True
+autosummary_imported_members = False
 
 # -- Options for numpydoc ------------------------------------------------
 numpydoc_attributes_as_param_list = False
@@ -124,16 +129,20 @@
 
 # -- Options for nbsphinx ------------------------------------------------
 
+nbsphinx_execute_arguments = [
+    "--InlineBackend.figure_formats={'svg', 'pdf'}",
+    "--InlineBackend.rc=figure.dpi=96",
+]
 # nbsphinx do not use requirejs (breaks bootstrap)
 nbsphinx_requirejs_path = ""
 
-# matplotlib plot directive settings
+# -- matplotlib plot directive settings -----------------------------------
 plot_html_show_formats = False
 plot_include_source = True
 plot_html_show_source_link = False
+plot_formats = [("png", 90)]
 plot_pre_code = """
 import numpy as np
-from matplotlib import pyplot as plt
 import okama as ok
 """
 
@@ -151,6 +160,3 @@
 # napoleon_use_rtype = True
 # napoleon_type_aliases = None
 # napoleon_attr_annotations = True
-
-# The encoding of source files.
-source_encoding = "utf-8"
diff --git a/docs/index.rst b/docs/index.rst
@@ -10,7 +10,7 @@
                 <img src="https://img.shields.io/badge/python-v3-brightgreen.svg"
                     alt="python"></a> &nbsp;
             <a href="https://pypi.org/project/okama/">
-                <img src="https://img.shields.io/badge/pypi-v1.0.0-brightgreen.svg"
+                <img src="https://img.shields.io/badge/pypi-v1.0.1-brightgreen.svg"
                     alt="pypi"></a> &nbsp;
             <a href='https://coveralls.io/github/mbk-dev/okama?branch=master'>
                 <img src='https://coveralls.io/repos/github/mbk-dev/okama/badge.svg?branch=master'
@@ -98,13 +98,28 @@ The latest development version can be installed directly from GitHub:
 
     The development version of *okama* can have technical and financial issues. Please use carefully at your own risk.
 
-Contents
-********
+
+Classes Overview
+****************
+
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 2
+    :caption: Quick Start
+
+    quickstart
+
+.. autosummary::
+    :toctree: stubs
+    :template: custom-class-template.rst
+    :caption: Main Classes
+
+    okama.Asset
+    okama.AssetList
+    okama.Portfolio
+
+
+Indices and tables
+******************
 
-    source/asset_list
-    source/portfolio
-    source/single_period
-    source/multi_period
-    source/plots
+* :ref:`genindex`
+* :ref:`search`
diff --git a/docs/make.bat b/docs/make.bat
@@ -1,4 +1,8 @@
 @ECHO OFF
+rem to remove everything from _build:
+rem make clean
+rem -E option is used to rebuild all
+rem make html -E
 
 pushd %~dp0
 

diff --git a/docs/quickstart.nblink b/docs/quickstart.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../examples/01 howto.ipynb"
+}
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -2,5 +2,7 @@ sphinx>=4.1.2
 sphinx_rtd_theme==0.5.2
 numpydoc==1.1.0
 nbsphinx==0.8.7
+nbsphinx-link>=1.3.0
+pandoc>=2.14.0
 recommonmark==0.7.1
 okama>=1.0.0
diff --git a/docs/rst.bat b/docs/rst.bat
@@ -1 +1,4 @@
+@ECHO OFF
+rem generate .rst sorce files
+
 sphinx-apidoc -o source/ ../okama
diff --git a/docs/source/asset_list.rst b/docs/source/asset_list.rst
diff --git a/docs/source/multi_period.rst b/docs/source/multi_period.rst
diff --git a/docs/source/plots.rst b/docs/source/plots.rst
diff --git a/docs/source/portfolio.rst b/docs/source/portfolio.rst
diff --git a/docs/source/single_period.rst b/docs/source/single_period.rst
diff --git a/examples/01 howto.ipynb b/examples/01 howto.ipynb
@@ -125,6 +125,13 @@
     "one_asset.dividends.tail(10)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Fiancial Databse: Tickers & Namespaces"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -183,7 +190,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Namespaces"
+    "Namespase is a set of characters after the period in the ticker (SPY**.US**)."
    ]
   },
   {
@@ -424,7 +431,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Compare several assets from different stock markets"
+    "## Compare assets from different stock markets"
    ]
   },
   {
@@ -933,7 +940,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Correlation Matrix"
+    "### Correlation Matrix"
    ]
   },
   {

diff --git a/okama/asset.py b/okama/asset.py
@@ -17,23 +17,6 @@ class Asset:
     ----------
     symbol: str, default "SPY.US"
         Symbol is an asset ticker with namespace after dot. The default value is "SPY.US" (SPDR S&P 500 ETF Trust).
-
-    Examples
-    --------
-    >>> asset = ok.Asset()
-    >>> asset
-    symbol                           SPY.US
-    name             SPDR S&P 500 ETF Trust
-    country                             USA
-    exchange                      NYSE ARCA
-    currency                            USD
-    type                                ETF
-    first date                      1993-02
-    last date                       2021-03
-    period length                      28.1
-    dtype: object
-
-    An Asset object could be easy created whithout specifying a symbol Asset() using the default symbol.
     """
 
     def __init__(self, symbol: str = default_ticker):
@@ -124,10 +107,19 @@ def close_monthly(self):
         """
         Return close price time series historical monthly data.
 
+        Monthly close time series not adjusted to for corporate actions: dividends and splits.
+
         Returns
         -------
         Series
             Time series of close price historical data (monthly).
+
+        Examples
+        --------
+        >>> import matplotlib.pyplot as plt
+        >>> x = ok.Asset('VOO.US')
+        >>> x.close_monthly.plot()
+        >>> plt.show()
         """
         return Frame.change_period_to_month(self.close_daily)
 

diff --git a/okama/asset_list.py b/okama/asset_list.py
@@ -64,6 +64,13 @@ def wealth_indexes(self) -> pd.DataFrame:
         -------
         DataFrame
             Time series of wealth index values for each asset and accumulated inflation.
+
+        Examples
+        --------
+        >>> import matplotlib.pyplot as plt
+        >>> x = ok.AssetList(['SPY.US', 'BND.US'])
+        >>> x.wealth_indexes.plot()
+        >>> plt.show()
         """
         df = self._add_inflation()
         return Frame.get_wealth_indexes(df)