From 78828369d39278cc88b8e07265b559b4a36c2079 Mon Sep 17 00:00:00 2001 From: Jimmy Situ Date: Sun, 26 May 2024 11:35:24 +0800 Subject: [PATCH] Add rtd files --- .readthedocs.yaml | 31 ++++++++++++++++++ README.md | 2 +- docs/Makefile | 20 ++++++++++++ docs/make.bat | 35 +++++++++++++++++++++ docs/requirements.txt | 58 ++++++++++++++++++++++++++++++++++ docs/source/api.rst | 10 ++++++ docs/source/conf.py | 73 +++++++++++++++++++++++++++++++++++++++++++ docs/source/index.md | 40 ++++++++++++++++++++++++ 8 files changed, 268 insertions(+), 1 deletion(-) create mode 100644 .readthedocs.yaml create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/requirements.txt create mode 100644 docs/source/api.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.md diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..44ee2f7 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,31 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.10" + # You can also specify other tool versions: + # nodejs: "16" + # rust: "1.55" + # golang: "1.17" + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/conf.py + +# If using Sphinx, optionally build your docs in additional formats such as PDF +# formats: +# - pdf + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: docs/requirements.txt + - method: pip + path: . diff --git a/README.md b/README.md index 2105a8c..e84606b 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ msfinance offers Pythonic way to download stocks financial data from [morningsta ![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/jimmysitu/msfinance/python-package.yml) -## Install +## Installation ```bash pip install msfinance ``` diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..747ffb7 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..c95df4d --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,58 @@ +# +# This file is autogenerated by pip-compile with python 3.10 +# To update, run: +# +# pip-compile docs/requirements.in +# +alabaster==0.7.12 + # via sphinx +babel==2.10.3 + # via sphinx +certifi==2022.6.15 + # via requests +charset-normalizer==2.1.0 + # via requests +docutils==0.17.1 + # via + # sphinx + # sphinx-rtd-theme +idna==3.3 + # via requests +imagesize==1.4.1 + # via sphinx +jinja2==3.1.2 + # via sphinx +markupsafe==2.1.1 + # via jinja2 +packaging==21.3 + # via sphinx +pygments==2.12.0 + # via sphinx +pyparsing==3.0.9 + # via packaging +pytz==2022.1 + # via babel +requests==2.28.1 + # via sphinx +snowballstemmer==2.2.0 + # via sphinx +sphinx==5.0.2 + # via + # -r docs/requirements.in + # sphinx-rtd-theme +sphinx-rtd-theme==1.0.0 + # via -r docs/requirements.in +sphinxcontrib-applehelp==1.0.2 + # via sphinx +sphinxcontrib-devhelp==1.0.2 + # via sphinx +sphinxcontrib-htmlhelp==2.0.0 + # via sphinx +sphinxcontrib-jsmath==1.0.1 + # via sphinx +sphinxcontrib-qthelp==1.0.3 + # via sphinx +sphinxcontrib-serializinghtml==1.1.5 + # via sphinx +urllib3==1.26.9 + # via requests diff --git a/docs/source/api.rst b/docs/source/api.rst new file mode 100644 index 0000000..01445a7 --- /dev/null +++ b/docs/source/api.rst @@ -0,0 +1,10 @@ +API +=== + +This page list all user's APIs of msfinance + +.. module:: msfinance.stocks +.. autoclass:: Stock + :members: +.. autoclass:: StockBase + :members: diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..3dbfa10 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,73 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html +import os +import sys + +sys.path.insert(0, os.path.abspath('../../')) + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'msfinance' +copyright = '2024, Jimmy Situ' +author = 'Jimmy Situ' +release = 'v0.2.2' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'myst_parser', # Markdown parser + 'sphinx.ext.duration', + 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon', + 'sphinx.ext.intersphinx', +] + +myst_enable_extensions = [ + "dollarmath", + "amsmath", + "deflist", + "fieldlist", + "tasklist", + "html_image", +] + + +# Napoleon settings +napoleon_google_docstring = True +napoleon_numpy_docstring = False +napoleon_include_init_with_doc = False +napoleon_include_private_with_doc = False +napoleon_include_special_with_doc = True +napoleon_use_admonition_for_examples = False +napoleon_use_admonition_for_notes = False +napoleon_use_admonition_for_references = False +napoleon_use_ivar = False +napoleon_use_param = True +napoleon_use_rtype = True +napoleon_preprocess_types = False +napoleon_type_aliases = None +napoleon_attr_annotations = True + + + +intersphinx_mapping = { + "rtd": ("https://docs.readthedocs.io/en/stable/", None), + "python": ("https://docs.python.org/3/", None), + "sphinx": ("https://www.sphinx-doc.org/en/master/", None), +} +intersphinx_disabled_domains = ["std"] + +templates_path = ['_templates'] +exclude_patterns = [] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_rtd_theme' +html_static_path = ['_static'] diff --git a/docs/source/index.md b/docs/source/index.md new file mode 100644 index 0000000..030c02e --- /dev/null +++ b/docs/source/index.md @@ -0,0 +1,40 @@ +# msfinance documentation. + +## Introduction +msfinance offers Pythonic way to download stocks financial data from [morningstar.com/stocks](https://www.morningstar.com/stocks) + +## Installation +```bash +pip install msfinance +``` + +## Quick Start +```python +#!/usr/bin/python3 -u +import msfinance as msf + +stock = msf.Stock( + session='msf_database.db3', +) + + +print(stock.get_income_statement('aapl', 'xnas')) +print(stock.get_balance_sheet_statement('aapl', 'xnas')) +print(stock.get_cash_flow_statement('aapl', 'xnas')) + +print(stock.get_growth('aapl', 'xnas')) +print(stock.get_operating_and_efficiency('aapl', 'xnas')) +print(stock.get_financial_health('aapl', 'xnas')) +print(stock.get_cash_flow('aapl', 'xnas')) +``` +- More example is placed in [example](https://github.com/jimmysitu/msfinance/tree/main/example) directory. Add msfinance path to environment variable: PYTHONPATH, and run examples directly + +## [API](api.rst) + + +```{toctree} +:maxdepth: 2 +:hidden: + +api +```