docs: change sphinx configuration

Jupyter Notebooks from examples can be used in docs

Author: chilango74

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 %}

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"

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`

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
 

docs/quickstart.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../examples/01 howto.ipynb"
+}

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

docs/rst.bat

@@ -1 +1,4 @@
+@ECHO OFF
+rem generate .rst sorce files
+
 sphinx-apidoc -o source/ ../okama