updated docs

jmfernandes · Oct 18, 2018 · 8f89444 · 8f89444
1 parent 0f3a4b4
commit 8f89444
Show file tree

Hide file tree

Showing 22 changed files with 301 additions and 66 deletions.
diff --git a/LICENSE.txt b/LICENSE.txt
@@ -1,4 +1,4 @@
-Copyright (c) 2018 The Python Packaging Authority (PyPA)
+Copyright (c) 2018 Joshua M. Fernandes
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

diff --git a/docs/source/_static/favicon.ico b/docs/source/_static/favicon.ico
diff --git a/docs/source/_static/pics/4295-8.jpg b/docs/source/_static/pics/4295-8.jpg
diff --git a/docs/source/_static/pics/robin.jpg b/docs/source/_static/pics/robin.jpg
diff --git a/docs/source/_static/pics/robinyell.jpg b/docs/source/_static/pics/robinyell.jpg
diff --git a/docs/source/_static/pics/title.PNG b/docs/source/_static/pics/title.PNG
diff --git a/docs/source/_static/pics/veyron.jpg b/docs/source/_static/pics/veyron.jpg
diff --git a/docs/source/_static/pics/wolf.jpg b/docs/source/_static/pics/wolf.jpg
diff --git a/docs/source/_static/pics/yacht.jpg b/docs/source/_static/pics/yacht.jpg
diff --git a/docs/source/_static/style.css b/docs/source/_static/style.css
@@ -0,0 +1,3 @@
+.note{
+  background-color: #FFF59C !important;
+}
diff --git a/docs/source/_templates/blurb.html b/docs/source/_templates/blurb.html
@@ -0,0 +1,3 @@
+<p>
+  Robin Stocks is the easy to use python wrapper for interacting with the Robinhood API.
+</p>
diff --git a/docs/source/_templates/button.html b/docs/source/_templates/button.html
@@ -0,0 +1,4 @@
+<!DOCTYPE html>
+
+<iframe src="https://ghbtns.com/github-btn.html?user=jmfernandes&repo=robin_stocks&type=star&count=true&size=large"
+frameborder="0" scrolling="0" width="160px" height="30px"></iframe>
diff --git a/docs/source/advanced.rst b/docs/source/advanced.rst
@@ -0,0 +1,49 @@
+
+Advanced Usage
+==============
+
+----
+
+.. image:: _static/pics/veyron.jpg
+
+Making Custom Get and Post Requests
+-----------------------------------
+
+Robin Stocks depends on Requests which you are free to call and use yourself, or you could
+use it within the Robin Stocks framework by using :func:`robin_stocks.helper.request_get`, :func:`robin_stocks.helper.request_post`,
+:func:`robin_stocks.helper.request_document`, and :func:`robin_stocks.helper.request_delete`. For example, if you wanted to make your own
+get request to the option instruments API endpoint in order to get all calls you would type:
+
+>>> url = 'https://api.robinhood.com/options/instruments/'
+>>> payload = { 'type' : 'call'}
+>>> robin_stocks.request_get(url,'regular',payload)
+
+Robinhood returns most data in the form::
+
+{ 'previous' : None, 'results' : [], 'next' : None}
+
+where 'results' is either a dictionary or a list of dictionaries. However, sometimes
+Robinhood returns the results dictionary directly. To compensate for this, I added
+the **dataType** parameter which defaults to 'regular'. There are four possible values and there uses are:
+
+>>> robin_stocks.request_get(url,'regular')    # For when the results are
+>>>                                            # returned directly or you
+>>>                                            # want to view 'next' or
+>>>                                            # 'previous' values.
+>>>
+>>> robin_stocks.request_get(url,'results')    # For when results contains a
+>>>                                            # list or dictionary.
+>>>
+>>> robin_stocks.request_get(url,'pagination') # For when results contains a
+>>>                                            # list, but you also want to
+>>>                                            # append any information in
+>>>                                            # 'next' to the list.
+>>>
+>>> robin_stocks.request_get(url,'indexzero')  # For when results is a list
+>>>                                            # of only one dictionary.
+
+Also keep in mind that the results from the Robinhood API have been decoded using ``.json()``.
+There are instances where the user does not want to decode the results (such as retrieving documents), so
+I added the :func:`robin_stocks.helper.request_document` function, which will always return the raw data,
+so there is no **dataType** parameter. :func:`robin_stocks.helper.request_post` is similar in that it only
+takes a url and payload parameter.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -21,6 +21,9 @@
 import sys
 sys.path.insert(0, os.path.abspath('../../'))
 
+def setup(app):
+    app.add_stylesheet('style.css')
+
 
 # -- General configuration ------------------------------------------------
 
@@ -80,6 +83,8 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+html_show_sourcelink = False
+
 
 # -- Options for HTML output ----------------------------------------------
 
@@ -92,13 +97,19 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {'page_width' : '1080px'}
 
 # 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']
 
+html_sidebars = {'**': ['blurb.html','button.html','globaltoc.html', 'sourcelink.html', 'searchbox.html']}
+
+html_logo = '_static/pics/title.PNG'
+
+html_favicon = '_static/favicon.ico'
+
 
 # -- Options for HTMLHelp output ------------------------------------------
 

diff --git a/docs/source/functions.rst b/docs/source/functions.rst
@@ -0,0 +1,58 @@
+
+List of All Functions
+=====================
+
+----
+
+.. note::
+
+  Even though the functions are written as ``robin_stocks.module.function``, the module
+  name is unimportant when calling a function. Simply use ``robin_stocks.function`` for all functions.
+
+Sending Requests to API
+-----------------------
+
+.. automodule:: robin_stocks.helper
+   :members: request_get,request_post,request_delete,request_document
+
+Logging In and Out
+------------------
+
+.. automodule:: robin_stocks.authentication
+   :members:
+
+Loading Profiles
+------------------
+
+.. automodule:: robin_stocks.profiles
+   :members:
+
+Getting Stock Information
+-------------------------
+
+.. automodule:: robin_stocks.stocks
+   :members:
+
+Getting Option Information
+--------------------------
+
+.. automodule:: robin_stocks.options
+   :members:
+
+Getting Market Information
+--------------------------
+
+.. automodule:: robin_stocks.markets
+   :members:
+
+Getting Positions and Account Information
+-----------------------------------------
+
+.. automodule:: robin_stocks.account
+   :members:
+
+Placing and Cancelling Orders
+-----------------------------
+
+.. automodule:: robin_stocks.orders
+   :members:
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -3,69 +3,42 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to robin_stocks's documentation!
-========================================
+Robin Stocks: Python Wrapper for Robinhood
+==========================================
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+-----
+
+.. image:: _static/pics/robin.jpg
 
 This library aims to create simple to use functions to interact with the
-Robinhood API. This is a pure python interface and it requires Python3. The purpose
+Robinhood API. This is a pure python interface and it requires Python 3. The purpose
 of this library is to allow people to make their own robo-investors or to view
 stock information in real time.
 
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
-Sending Requests to API
------------------------
-
-.. automodule:: robin_stocks.helper
-   :members: request_get,request_post,request_delete,request_document
-
-Logging In and Out
-------------------
-
-.. automodule:: robin_stocks.authentication
-   :members:
+.. note::
 
-Loading Profiles
-------------------
+  These functions make real time calls to your Robinhood account. Unlike in the app, there are
+  no warnings when you are about to buy, sell, or cancel an order. It is up to **YOU** to use
+  these commands responsibly.
 
-.. automodule:: robin_stocks.profiles
-   :members:
+User Guide
+==========
 
-Getting Stock Information
--------------------------
+Below is the table of contents for Robin Stocks. Use it to find example code or
+to scroll through the list of all the callable functions.
 
-.. automodule:: robin_stocks.stocks
-   :members:
-
-Getting Option Information
---------------------------
-
-.. automodule:: robin_stocks.options
-   :members:
-
-Getting Market Information
---------------------------
-
-.. automodule:: robin_stocks.markets
-   :members:
-
-Getting Positions and Account Information
------------------------------------------
+.. toctree::
+   :maxdepth: 3
 
-.. automodule:: robin_stocks.account
-   :members:
+   intro
+   install
+   quickstart
+   advanced
+   functions
 
-Placing and Cancelling Orders
------------------------------
+Indices and tables
+==================
 
-.. automodule:: robin_stocks.orders
-   :members:
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/source/install.rst b/docs/source/install.rst
@@ -0,0 +1,27 @@
+
+Installing
+==========
+
+----
+
+.. image:: _static/pics/yacht.jpg
+
+Using Pip
+---------
+
+This is the simplest method. To install Robin Stocks globally or inside a virtual environment,
+open terminal and run the command::
+
+$ pip install robin-stocks
+
+Get The Source Code
+-------------------
+
+If you prefer to install the source code directly, it can be found `here <https://github.com/jmfernandes/robin_stocks>`_,
+or you can clone the repository using::
+
+$ git clone https://github.com/jmfernandes/robin_stocks.git
+
+Once the file has been downloaded or cloned, cd into the directory that contains the ``setup.py`` file and install using::
+
+$ pip install .
diff --git a/docs/source/intro.rst b/docs/source/intro.rst
@@ -0,0 +1,62 @@
+
+Introduction
+============
+
+----
+
+.. image:: _static/pics/wolf.jpg
+
+Philosophy
+----------
+
+I've written the code in accordance with what I consider the best coding practices.
+Some of these are part of `PEP 20 <https://www.python.org/dev/pep-0020>`_ standards and some are my own. They are as follows:
+
+* Explicit is better than implicit
+
+This is the reason why my code uses ``import robin_stocks.module as module`` instead of ``from module import *``.
+This means that calls to a function from the module must be written as ``module.function`` instead of the simply
+``function``. When viewing the code, it's easy to see which functions come from which modules.
+
+* Flat is better than nested
+
+The __init__.py file contains an import of all the functions I want to be made public to the user. This allows
+the user to call ``robin_stocks.function`` for all functions. Without the imports, the user would have to call
+``robin_stocks.module.function`` and be sure to use the correct module name every single time. This may seem contradictory
+to the first standard, but the difference is that whereas I the developer must make explicit calls, for the end user it is
+unnecessary.
+
+* Three strikes and you refactor
+
+If you find yourself copying and pasting the same code 3 or more times, then it means you should put that code in
+its own function. Thus, I created the ``request_get`` and ``filter`` functions, and then provided input parameters to
+handle different use cases.
+
+* Type is in the name
+
+A person should be able to look at the code and know the purpose of all the names they see. For this reason
+I have written names of functions as ``snake_case``, names of input parameters and local function variables as
+``camelCase``, and names of global variables, class names, and enum names as ``PascalCase``
+
+License
+-------
+
+Copyright (c) 2018 Joshua M. Fernandes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst
@@ -0,0 +1,40 @@
+
+Quick Start
+============
+
+----
+
+.. image:: _static/pics/robinyell.jpg
+
+Importing and Logging In
+------------------------
+
+The first thing you will need to do is to import Robin Stocks by typing:
+
+>>> import robin_stocks
+
+robin_stocks will need to added as a preface to every function call in the form of ``robin_stocks.function``.
+If you don't want to have to type robin_stocks at the beginning of every call,
+then import Robin Stocks by typing
+
+>>> from robin_stocks import *
+
+Keep in mind that this method is not considered good practice as it obfuscates the distinction between Robin Stocks'
+functions and other functions. For the rest of the documentation, I will assume that Robin Stocks was imported as ``import robin_stocks``.
+
+Once you have imported Robin Stocks, you will need to login in order to store an authentication token using
+
+>>> robin_stocks.login(<username>,<password>)
+
+Not all functions require authentication, but its good practice to log in to Robinhood at the beginning of your script.
+
+
+Building Profile and User Data
+------------------------------
+
+The two most useful functions are ``build_holdings`` and ``build_user_profile``. These condense information from several
+functions into a single dictionary. If you wanted to view all your holdings then type:
+
+>>> my_stocks = robin_stocks.build_holdings()
+>>> for key,value in my_stocks.items():
+>>>     print(key,value)