add sphinx docs

.gitignore

@@ -55,7 +55,7 @@ venv/
 *.log
 
 # Sphinx documentation
-docs/_build/
+docs/build/
 
 # PyBuilder
 target/

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
+	POLYGON_API_KEY="POLYGON_API_KEY" $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/Getting-Started.rst

@@ -0,0 +1,176 @@
+Getting Started
+===============
+
+Requirements:
+  - `Polygon.io API key <https://polygon.io/dashboard/api-keys>`_
+  - `Python >= 3.7 <https://www.python.org/downloads/>`_
+  - `This package <https://pypi.org/project/polygon-api-client/>`_
+
+.. code-block:: shell
+
+    pip install polygon-api-client
+
+HTTP client usage
+-----------------
+
+.. automethod:: polygon.RESTClient.__init__
+
+You can pass your API key via the environment variable :code:`POLYGON_API_KEY` or as the first parameter to the :code:`RESTClient` constructor:
+
+.. code-block:: python
+
+  from polygon import RESTClient
+
+  client = RESTClient() # POLYGON_API_KEY is used
+  client = RESTClient("api_key") # api_key is used
+
+For non-paginated endpoints call :code:`get_*`:
+
+.. code-block:: python
+
+  aggs = client.get_aggs("AAPL", 1, "day", "2022-04-01", "2022-04-04")
+  print(aggs)
+
+For paginated endpoints call :code:`list_*` and use the provided iterator:
+
+.. code-block:: python
+
+  trades = []
+  for t in client.list_trades("AAA", timestamp="2022-04-20", limit=5, sort=Sort.ASC)
+      trades.append(t)
+  print(trades)
+
+For endpoints that have a set of parameters you can use the provided enums:
+
+.. code-block:: python
+
+  from polygon.rest.models import Sort
+
+  client.list_trades(..., sort=Sort.ASC)
+
+To handle the raw `urllib3 response <https://urllib3.readthedocs.io/en/stable/reference/urllib3.response.html?highlight=response#response) yourself, pass `raw=True>`_ yourself pass :code:`raw=True`:
+
+.. code-block:: python
+
+  aggs = client.get_aggs("AAPL", 1, "day", "2022-04-01", "2022-04-04", raw=True)
+  print(aggs.geturl())
+  # https://api.polygon.io/v2/aggs/ticker/AAPL/range/1/day/2022-04-01/2022-04-04
+  print(aggs.status)
+  # 200
+  print(aggs.data)
+  # b'{
+  #    "ticker": "AAPL",
+  #    "queryCount": 2,
+  #    "resultsCount": 2,
+  #    "adjusted": true,
+  #    "results": [
+  #      {
+  #        "v": 78251328,
+  #        "vw": 173.4143,
+  #        "o": 174.03,
+  #        "c": 174.31,
+  #        "h": 174.88,
+  #        "l": 171.94,
+  #        "t": 1648785600000,
+  #        "n": 661160
+  #      },
+  #      {
+  #        "v": 76545983,
+  #        "vw": 177.4855,
+  #        "o": 174.57,
+  #        "c": 178.44,
+  #        "h": 178.49,
+  #        "l": 174.44,
+  #        "t": 1649044800000,
+  #        "n": 630374
+  #      }
+  #    ],
+  #    "status": "OK",
+  #    "request_id": "d8882a9d5194978819777f49c44b09c6",
+  #    "count": 2
+  #  }'
+
+If it is a paginated :code:`list_*` response it's up to you to handle the "next_url" iteration:
+
+.. code-block:: python
+
+  trades = client.list_trades("AAA", timestamp="2022-04-20", limit=5)
+  print(aggs.data)
+  # b'{
+  #  "results": [
+  #    {
+  #      "conditions": [
+  #        15
+  #      ],
+  #      "exchange": 11,
+  #      "id": "52983575627601",
+  #      "participant_timestamp": 1650499200029279200,
+  #      "price": 24.875,
+  #      "sequence_number": 1591291,
+  #      "sip_timestamp": 1650499200029316600,
+  #      "size": 100,
+  #      "tape": 1
+  #    },
+  #    {
+  #      "conditions": [
+  #        38,
+  #        41
+  #      ],
+  #      "exchange": 11,
+  #      "id": "52983575627600",
+  #      "participant_timestamp": 1650499200029279200,
+  #      "price": 24.875,
+  #      "sequence_number": 1591290,
+  #      "sip_timestamp": 1650499200029316600,
+  #      "tape": 1
+  #    },
+  #    {
+  #      "conditions": [
+  #        15
+  #      ],
+  #      "exchange": 11,
+  #      "id": "52983575622470",
+  #      "participant_timestamp": 1650493800003024000,
+  #      "price": 24.875,
+  #      "sequence_number": 1571279,
+  #      "sip_timestamp": 1650493800003645400,
+  #      "size": 100,
+  #      "tape": 1
+  #    },
+  #    {
+  #      "conditions": [
+  #        38,
+  #        41
+  #      ],
+  #      "exchange": 11,
+  #      "id": "52983575622469",
+  #      "participant_timestamp": 1650493800003024000,
+  #      "price": 24.875,
+  #      "sequence_number": 1571276,
+  #      "sip_timestamp": 1650493800003635500,
+  #      "tape": 1
+  #    },
+  #    {
+  #      "conditions": [
+  #        15
+  #      ],
+  #      "exchange": 11,
+  #      "id": "52983575556178",
+  #      "participant_timestamp": 1650485400002987800,
+  #      "price": 24.875,
+  #      "sequence_number": 1536223,
+  #      "sip_timestamp": 1650485400003870000,
+  #      "size": 100,
+  #      "tape": 1
+  #    }
+  #  ],
+  #  "status": "OK",
+  #  "request_id": "618bb99e7a632ed9f55454a541404b44",
+  #  "next_url": "https://api.polygon.io/v3/trades/AAA?cursor=YXA9NSZhcz0mbGltaXQ9NSZvcmRlcj1kZXNjJnNvcnQ9dGltZXN0YW1wJnRpbWVzdGFtcC5ndGU9MjAyMi0wNC0yMFQwNCUzQTAwJTNBMDBaJnRpbWVzdGFtcC5sdGU9MjAyMi0wNC0yMFQyMCUzQTEwJTNBMDAuMDAzODY5OTUyWg"
+  # }'
+
+
+Websocket client usage
+----------------------
+
+Coming soon.

docs/source/Quotes.rst

@@ -0,0 +1,15 @@
+.. _quotes_header:
+
+Quotes
+==========
+
+===========
+List quotes
+===========
+
+.. automethod:: polygon.RESTClient.list_quotes
+
+==============
+Get last quote
+==============
+.. automethod:: polygon.RESTClient.get_last_quote

docs/source/Reference.rst

@@ -0,0 +1,40 @@
+.. _reference_header:
+
+Reference
+===============
+
+====================
+List market holidays
+====================
+.. automethod:: polygon.RESTClient.list_market_holidays
+
+====================
+List tickers
+====================
+.. automethod:: polygon.RESTClient.list_tickers
+
+====================
+List ticker details
+====================
+.. automethod:: polygon.RESTClient.get_ticker_details
+
+====================
+Get ticker news
+====================
+.. automethod:: polygon.RESTClient.get_ticker_news
+
+====================
+Get ticker types
+====================
+.. automethod:: polygon.RESTClient.get_ticker_types
+
+====================
+List splits
+====================
+.. automethod:: polygon.RESTClient.list_splits
+
+====================
+List dividends
+====================
+.. automethod:: polygon.RESTClient.list_dividends
+

docs/source/Trades.rst

@@ -0,0 +1,9 @@
+.. _trades_header:
+
+Trades
+=============
+
+===========
+List trades
+===========
+.. automethod:: polygon.RESTClient.list_trades

docs/source/conf.py

@@ -0,0 +1,59 @@
+# 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
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../..'))
+print('docs path', sys.path[0])
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'polygon-api-client'
+copyright = '2022, Polygon.io'
+author = 'Polygon.io'
+
+# The full version, including alpha/beta/rc tags
+release = '0.3.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx_autodoc_typehints',
+    'sphinx_rtd_theme',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/source/index.rst

@@ -0,0 +1,21 @@
+Welcome to polygon-api-client's documentation!
+==============================================
+
+This documentation is for the Python client only. For details about the responses see `the official docs <https://polygon.io/docs>`_.
+
+.. toctree::
+  :maxdepth: 1
+  :caption: Contents:
+
+  Getting-Started
+  Quotes
+  Reference
+  Trades
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`