Documentation overhaul

2020-05-28 18:33:36 +00:00
parent e6469aea5f
commit 2abf195391
12 changed files with 323 additions and 168 deletions
@@ -1,10 +1,15 @@
 .. toctree::
   :titlesonly:
   :maxdepth: 1
 =========
 Changelog
-----------
+=========
 A list of changes between each release
 0.15.0 (2020-05-08)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 **Breaking Changes:**
 - Removed support for Python 3.5 (3.6 is now the minimum supported version)
@@ -29,7 +34,7 @@ This can be used by instantiating the Blink class with the ``device_id`` paramet
 - Fix typos (`#244 <https://github.com/fronzbot/blinkpy/pull/244>`__)
 0.14.3 (2020-04-22)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - Add time check on recorded videos before determining motion
 - Fix motion detection variable suck to ``True``
 - Add ability to load credentials from a json file
@@ -37,18 +42,18 @@ This can be used by instantiating the Blink class with the ``device_id`` paramet
 - Log response message from server if not attempting a re-authorization
 0.14.2 (2019-10-12)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - Update dependencies
 - Dockerize `(@3ch01c <https://github.com/fronzbot/blinkpy/pull/198>__)`
 0.14.1 (2019-06-20)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - Fix timeout problems blocking blinkpy startup
 - Updated login urls using ``rest-region`` subdomain
 - Removed deprecated thumbanil recovery from homescreen
 0.14.0 (2019-05-23)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 **Breaking Changes:**
 - ``BlinkCamera.battery`` no longer reports a percentage, instead it returns a string representing the state of the battery.
@@ -70,11 +75,11 @@ This can be used by instantiating the Blink class with the ``device_id`` paramet
 0.13.1 (2019-03-01)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - Remove throttle decorator from network status request
 0.13.0 (2019-03-01)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 **Breaking change:**
 Wifi status reported in dBm again, instead of bars (which is great).  Also, the old ``get_camera_info`` method has changed and requires a ``camera_id`` parameter.
@@ -99,11 +104,11 @@ Wifi status reported in dBm again, instead of bars (which is great).  Also, the
 0.12.1 (2019-01-31)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - Remove logging improvements since they were incompatible with home-assistant logging
 0.12.0 (2019-01-31)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - Fix video api endpoint, re-enables motion detection
 - Add improved logging capability
 - Add download video method
@@ -111,22 +116,22 @@ Wifi status reported in dBm again, instead of bars (which is great).  Also, the
 0.11.2 (2019-01-23)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - Hotfix to prevent platform from stalling due to API change
 - Motion detection and video recovery broken until new API endpoint discovered
 0.11.1 (2019-01-02)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - Fixed incorrect backup login url
 - Added calibrated temperature property for cameras
 0.11.0 (2018-11-23)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - Added support for multiple sync modules
 0.10.3 (2018-11-18)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - Use networks endpoint rather than homecreen to retrieve arm/disarm status (`@md-reddevil <https://github.com/fronzbot/blinkpy/pull/119>`__)
 - Fix incorrect command status endpoint (`@md-reddevil <https://github.com/fronzbot/blinkpy/pull/118>`__)
 - Add extra debug logging
@@ -134,18 +139,18 @@ Wifi status reported in dBm again, instead of bars (which is great).  Also, the
 0.10.2 (2018-10-30)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - Set minimum required version of the requests library to 2.20.0 due to vulnerability in earlier releases.
 - When multiple networks detected, changed log level to ``warning`` from ``error`` 
 0.10.1 (2018-10-18)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - Fix re-authorization bug (fixes `#101 <https://github.com/fronzbot/blinkpy/issues/#101>`__)
 - Log an error if saving video that doesn't exist
 0.10.0 (2018-10-16)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - Moved all API calls to own module for easier maintainability
 - Added network ids to sync module and cameras to allow for multi-network use
 - Removed dependency on video existance prior to camera setup (fixes `#93 <https://github.com/fronzbot/blinkpy/issues/#93>`__)
@@ -157,7 +162,7 @@ Wifi status reported in dBm again, instead of bars (which is great).  Also, the
 - Check if retrieved clip is "None" prior to storing in cache
 0.9.0 (2018-09-27)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - Complete code refactoring to enable future multi-sync module support
 - Add image and video caching to the cameras
 - Add internal throttling of system refresh
@@ -168,7 +173,7 @@ Wifi status reported in dBm again, instead of bars (which is great).  Also, the
 0.8.1 (2018-09-24)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - Update requirements_test.txt
 - Update linter versions
 - Fix pylint warnings
@@ -184,18 +189,18 @@ Wifi status reported in dBm again, instead of bars (which is great).  Also, the
  - Reset the value every system refresh
 0.8.0 (2018-05-21)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - Added support for battery voltage level (fixes `#64 <https://github.com/fronzbot/blinkpy/issues/64>`__)
 - Added motion detection per camera
 - Added fully accessible camera configuration dict
 - Added celcius property to camera (fixes `#60 <https://github.com/fronzbot/blinkpy/issues/60>`__)
 0.7.1 (2018-05-09)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - Fixed pip 10 import issue during setup (`@fronzbot <https://github.com/fronzbot/blinkpy/pull/61>`__)
 0.7.0 (2018-02-08)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - Fixed style errors for bumped pydocstring and pylint versions
 - Changed Blink.cameras dictionary to be case-insensitive (fixes `#35 <https://github.com/fronzbot/blinkpy/issues/35>`__)
 - Changed api endpoint for video extraction (fixes `#35 <https://github.com/fronzbot/blinkpy/issues/35>`__ and `#41 <https://github.com/fronzbot/blinkpy/issues/41>`__)
@@ -209,7 +214,7 @@ Wifi status reported in dBm again, instead of bars (which is great).  Also, the
 - Added ``attributes`` dictionary to camera object
 0.6.0 (2017-05-12)
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 - Removed redundent properties that only called hidden variables
 - Revised request wrapper function to be more intelligent
 - Added tests to ensure exceptions are caught and handled (100% coverage!)
@@ -217,44 +222,44 @@ Wifi status reported in dBm again, instead of bars (which is great).  Also, the
 - Added battery level string to reduce confusion with the way Blink reports battery level as integer from 0 to 3
 0.5.2 (2017-03-12)
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 - Fixed packaging mishap, same as 0.5.0 otherwise
 0.5.0 (2017-03-12)
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 - Fixed region handling problem
 - Added rest.piri subdomain as a backup if region can't be found
 - Improved the file writing function
 - Large test coverage increase
 0.4.4 (2017-03-06)
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 - Fixed bug where region id was not being set in the header
 0.4.3 (2017-03-05)
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 - Changed to bdist_wheel release
 0.4.2 (2017-01-28)
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 - Fixed inability to retrieve motion data due to Key Error
 0.4.1 (2017-01-27)
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 - Fixed refresh bug (0.3.1 did not actually fix the problem)
 - Image refresh routine added (per camera)
 - Dictionary of thumbnails per camera added
 - Improved test coverage
 0.3.1 (2017-01-25)
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 - Fixed refresh bug (Key Error)
 0.3.0 (2017-01-25)
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 - Added device id to camera lookup table
 - Added image to file method
 0.2.0 (2017-01-21)
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 - Initial release of blinkpy
@@ -1,98 +0,0 @@
 # Contributing to blinkpy
 Everyone is welcome to contribute to blinkpy! The process to get started is described below.
 ## Fork the Repository
 You can do this right in github: just click the 'fork' button at the top right.
 ## Start Developing
 1. Setup Local Repository
   ```shell
   $ git clone https://github.com/<YOUR_GIT_USERNAME>/blinkpy.git
   $ cd blinkpy
   $ git remote add upstream https://github.com/fronzbot/blinkpy.git
   ```
 2. Create virtualenv and install dependencies
   ```shell
   $ python -m venv venv
   $ source venv/bin/activate
   $ pip install -r requirements.txt
   $ pip install -r requirements_test.txt
   $ pre-commit install
   ```
 3. Create a Local Branch
   First, you will want to create a new branch to hold your changes:
   ``git checkout -b <your-branch-name>``
 4. Make changes
   Now you can make changes to your code.  It is worthwhile to test your code as you progress (see the **Testing** section)
 5. Commit Your Changes
   To commit changes to your branch, simply add the files you want and the commit them to the branch.  After that, you can push to your fork on GitHub:
   ```shell
   $ git add .
   $ git commit -m "Put your commit text here.  Please be concise, but descriptive."
   $ git push origin HEAD
   ```
 6. Submit your pull request on GitHub
   - On GitHub, navigate to the [blinkpy](https://github.com/fronzbot/blinkpy) repository.
   - In the "Branch" menu, choose the branch that contains your commits (from your fork).
   - To the right of the Branch menu, click New pull request.
   - The base branch dropdown menu should read `dev`. Use the compare branch drop-down menu to choose the branch you made your changes        in.
   - Type a title and complete the provided description for your pull request.
   - Click Create pull request.
   - More detailed instructions can be found here: [Creating a Pull Request](https://help.github.com/articles/creating-a-pull-request/)
 7. Prior to merge approval
   Finally, the `blinkpy` repository uses continuous integration tools to run tests prior to merging. If there are any problems, you      will see a red 'X' next to your pull request. To see what's wrong, you can find your pull request [here](https://travis-       ci.org/fronzbot/blinkpy/pull_requests) and click on the failing test to see the logs.  Those logs will indicate, as best as they can, what is causing that test to fail.
 ## Testing
 It is important to test the code to make sure your changes don't break anything major and that they pass PEP8 style conventions.
 First, you need to locally install ``tox``
 ```shell
 $ pip3 install tox
 ```
 You can then run all of the tests with the following command:
 ```shell
 $ tox
 ```
 ### Tips
 If you only want to see if you can pass the local tests, you can run `tox -e py35` (or whatever python version you have installed.  Only `py35`, `py36`, and `py37` will be accepted).  If you just want to check for style violations, you can run `tox -e lint`.  Regardless, when you submit a pull request, your code MUST pass both the unit tests, and the linters.
 If you need to change anything in `requirements.txt` for any reason, you'll want to regenerate the virtual envrionments used by `tox` by running with the `-r` flag: `tox -r`
 If you want to run a single test (perhaps you only changed a small thing in one file) you can run `tox -e py35 -- tests/<testname>.py -x`.  This will run the test `<testname>.py` and stop testing upon the first failure, making it easier to figure out why a particular test might be failing.  The test structure mimics the library structure, so if you changed something in `sync_module.py`, the associated test file would be in `test_sync_module.py` (ie. the filename is prepended with `test_`.
 # Catching Up With Reality
 If your code is taking a while to develop, you may be behind the ``dev`` branch, in which case you need to catch up before creating your pull-request.  To do this you can run ``git rebase`` as follows (running this on your local branch):
 ```shell
 $ git fetch upstream dev
 $ git rebase upstream/dev
 ```
 If rebase detects conflicts, repeat the following process until all changes have been resolved:
 1. ``git status`` shows you the filw with a conflict.  You will need to edit that file and resolve the lines between ``<<<< | >>>>`.
 2. Add the modified file: ``git add <file>`` or ``git add .``.
 3. Continue rebase: ``git rebase --continue``.
 4. Repeat until all conflicts resolved.
@@ -0,0 +1,109 @@
 ========================
 Contributing to blinkpy
 ========================
 Everyone is welcome to contribute to blinkpy! The process to get started is described below.
 Fork the Repository
 -------------------
 You can do this right in github: just click the 'fork' button at the top right.
 Start Developing
 -----------------
 1. Setup Local Repository
   .. code:: bash
       $ git clone https://github.com/<YOUR_GIT_USERNAME>/blinkpy.git
       $ cd blinkpy
       $ git remote add upstream https://github.com/fronzbot/blinkpy.git
 2. Create virtualenv and install dependencies
   .. code:: bash
       $ python -m venv venv
       $ source venv/bin/activate
       $ pip install -r requirements.txt
       $ pip install -r requirements_test.txt
       $ pre-commit install
 3. Create a Local Branch
   First, you will want to create a new branch to hold your changes:
   ``git checkout -b <your-branch-name>``
 4. Make changes
   Now you can make changes to your code.  It is worthwhile to test your code as you progress (see the **Testing** section)
 5. Commit Your Changes
   To commit changes to your branch, simply add the files you want and the commit them to the branch.  After that, you can push to your fork on GitHub:
   .. code:: bash
       $ git add .
       $ git commit
       $ git push origin HEAD
 6. Submit your pull request on GitHub
   - On GitHub, navigate to the `blinkpy <https://github.com/fronzbot/blinkpy>`__ repository.
   - In the "Branch" menu, choose the branch that contains your commits (from your fork).
   - To the right of the Branch menu, click New pull request.
   - The base branch dropdown menu should read ``dev``. Use the compare branch drop-down menu to choose the branch you made your changes        in.
   - Type a title and complete the provided description for your pull request.
   - Click Create pull request.
   - More detailed instructions can be found here: `Creating a Pull Request` <https://help.github.com/articles/creating-a-pull-request>`__
 7. Prior to merge approval
   Finally, the ``blinkpy`` repository uses continuous integration tools to run tests prior to merging. If there are any problems, you  will see a red 'X' next to your pull request.
 Testing
 -------
 It is important to test the code to make sure your changes don't break anything major and that they pass PEP8 style conventions.
 First, you need to locally install ``tox``
 .. code:: bash
    $ pip install tox
 You can then run all of the tests with the following command:
 .. code:: bash
    $ tox
 **Tips**
 If you only want to see if you can pass the local tests, you can run ``tox -e py37`` (or whatever python version you have installed.  Only ``py36``, ``py37``, and ``py38`` will be accepted).  If you just want to check for style violations, you can run ``tox -e lint``.  Regardless, when you submit a pull request, your code MUST pass both the unit tests, and the linters.
 If you need to change anything in ``requirements.txt`` for any reason, you'll want to regenerate the virtual envrionments used by ``tox`` by running with the ``-r`` flag: ``tox -r``
 If you want to run a single test (perhaps you only changed a small thing in one file) you can run ``tox -e py37 -- tests/<testname>.py -x``.  This will run the test ``<testname>.py`` and stop testing upon the first failure, making it easier to figure out why a particular test might be failing.  The test structure mimics the library structure, so if you changed something in ``sync_module.py``, the associated test file would be in ``test_sync_module.py`` (ie. the filename is prepended with ``test_``.
 Catching Up With Reality
 -------------------------
 If your code is taking a while to develop, you may be behind the ``dev`` branch, in which case you need to catch up before creating your pull-request.  To do this you can run ``git rebase`` as follows (running this on your local branch):
 .. code:: bash
    $ git fetch upstream dev
    $ git rebase upstream/dev
 If rebase detects conflicts, repeat the following process until all changes have been resolved:
 1. ``git status`` shows you the filw with a conflict.  You will need to edit that file and resolve the lines between ``<<<< | >>>>``.
 2. Add the modified file: ``git add <file>`` or ``git add .``.
 3. Continue rebase: ``git rebase --continue``.
 4. Repeat until all conflicts resolved.
@@ -6,8 +6,7 @@ Like the library? Consider buying me a cup of coffee!
 |Donate|
-Disclaimer:
+**Disclaimer:**
 ~~~~~~~~~~~~~~~
 Published under the MIT license - See LICENSE file for more details.
 "Blink Wire-Free HS Home Monitoring & Alert Systems" is a trademark owned by Immedia Inc., see www.blinkforhome.com for more information.
@@ -18,11 +17,11 @@ Original protocol hacking by MattTW : https://github.com/MattTW/BlinkMonitorProt
 API calls faster than 60 seconds is not recommended as it can overwhelm Blink's servers.  Please use this module responsibly.
 Installation
-================
+-------------
-``pip3 install blinkpy``
+``pip install blinkpy``
 Installing Development Version
-==================================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 To install the current development version, perform the following steps.  Note that the following will create a blinkpy directory in your home area:
 .. code:: bash
@@ -35,12 +34,12 @@ To install the current development version, perform the following steps.  Note t
    $ pip3 install --upgrade dist/*.whl
-If you'd like to contribute to this library, please read the `contributing instructions <https://github.com/fronzbot/blinkpy/blob/dev/CONTRIBUTING.md>`__.
+If you'd like to contribute to this library, please read the `contributing instructions <https://github.com/fronzbot/blinkpy/blob/dev/CONTRIBUTING.rst>`__.
 For more information on how to use this library, please `read the docs <https://blinkpy.readthedocs.io/en/latest/>`__.
 Purpose
-===========
+-------
 This library was built with the intention of allowing easy communication with Blink camera systems, specifically to support the `Blink component <https://home-assistant.io/components/blink>`__ in `homeassistant <https://home-assistant.io/>`__.
 Quick Start
@@ -58,7 +57,7 @@ The simplest way to use this package from a terminal is to call ``Blink.start()`
 This flow will prompt you for your username and password.  Once entered, if you likely will need to send a 2FA key to the blink servers (this pin is sent to your email address).  When you receive this pin, enter at the prompt and the Blink library will proceed with setup.
 Starting blink without a prompt
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
 In some cases, having an interactive command-line session is not desired.  In this case, you will need to set the ``Blink.auth.no_prompt`` value to ``True``.  In addition, since you will not be prompted with a username and password, you must supply the login data to the blink authentication handler.  This is best done by instantiating your own auth handler with a dictionary containing at least your username and password.
 .. code:: python
@@ -82,7 +81,7 @@ Since you will not be prompted for any 2FA pin, you must call the ``blink.auth.s
 Supplying credentials from file
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------
 Other use cases may involved loading credentials from a file.  This file must be ``json`` formatted and contain a minimum of ``username`` and ``password``.  A built in function in the ``blinkpy.helpers.util`` module can aid in loading this file.  Note, if ``no_prompt`` is desired, a similar flow can be followed as above.
 .. code:: python
@@ -98,7 +97,7 @@ Other use cases may involved loading credentials from a file.  This file must be
 Saving credentials
-~~~~~~~~~~~~~~~~~~~
+-------------------
 This library also allows you to save your credentials to use in future sessions.  Saved information includes authentication tokens as well as unique ids which should allow for a more streamlined experience and limits the frequency of login requests.  This data can be saved as follows (it can then be loaded by following the instructions above for supplying credentials from a file):
 .. code:: python
@@ -107,7 +106,7 @@ This library also allows you to save your credentials to use in future sessions.
 Getting cameras
-~~~~~~~~~~~~~~~~
+----------------
 Cameras are instantiated as individual ``BlinkCamera`` classes within a ``BlinkSyncModule`` instance.  All of your sync modules are stored within the ``Blink.sync`` dictionary and can be accessed using the name of the sync module as the key (this is the name of your sync module in the Blink App).
 The below code will display cameras and their available attributes:
@@ -138,8 +137,43 @@ The ``blinkpy`` api also allows for saving images and videos to a file and snapp
    camera.image_to_file('/local/path/for/image.jpg')
    camera.video_to_file('/local/path/for/video.mp4')
 Arming Blink
 -------------
 Methods exist to arm/disarm the sync module, as well as enable/disable motion detection for individual cameras.  This is done as follows:
 .. code:: python
    # Arm a sync module
    blink.sync["SYNC MODULE NAME"].arm = True
    # Disarm a sync module
    blink.sync["SYNC MODULE NAME"].disarm = False
    # Print arm status of a sync module - a system refresh should be performed first
    blink.refresh()
    sync = blink.sync["SYNC MODULE NAME"]
    print(f"{sync.name} status: {sync.arm}")
 Similar methods exist for individual cameras:
 .. code:: python
   camera = blink.cameras["SOME CAMERA NAME"]
   # Enable motion detection on a camera
   camera.arm = True
   # Disable motion detection on a camera
   camera.arm = False
   # Print arm status of a sync module - a system refresh should be performed first
   blink.refresh()
   print(f"{camera.name} status: {camera.arm}")
 Download videos
-~~~~~~~~~~~~~~~~
+----------------
 You can also use this library to download all videos from the server.  In order to do this, you must specify a ``path``.  You may also specifiy a how far back in time to go to retrieve videos via the ``since=`` variable (a simple string such as ``"2017/09/21"`` is sufficient), as well as how many pages to traverse via the ``page=`` variable.  Note that by default, the library will search the first ten pages which is sufficient in most use cases.  Additionally, you can specidy one or more cameras via the ``camera=`` property.  This can be a single string indicating the name of the camera, or a list of camera names.  By default, it is set to the string ``'all'`` to grab videos from all cameras.
 Example usage, which downloads all videos recorded since July 4th, 2018 at 9:34am to the ``/home/blink`` directory:
@@ -0,0 +1 @@
 ../CHANGES.rst
@@ -0,0 +1 @@
 ../CONTRIBUTING.rst
@@ -0,0 +1,81 @@
 =======================
 Advanced Library Usage
 =======================
 Usage of this library was designed with the `Home Assistant <https://home-assistant.io>`__ project in mind.  With that said, this library is flexible to be used in other scripts where advanced usage not covered in the Quick Start guide may be required.  This usage guide will attempt to cover as many use cases as possible.
 Throttling
 --------------
 In general, attempting too many requests to the Blink servers will result in your account being throttled.  Where possible, adding a delay between calls is ideal.  For use cases where this is not an acceptable solution, the ``blinkpy.helpers.util`` module contains a ``Throttle`` class that can be used as a decorator for calls.  There are many examples of usage within the ``blinkpy.api`` module.  A simple example of usage is covered below, where the decorated method is prevented from executing again until 10s has passed.  Note that if the method call is throttled by the decorator, the method will return `None`.
 .. code:: python
   from blinkpy.helpers.util import Throttle
   @Throttle(seconds=10)
   def my_method(*args):
       """Some method to be throttled."""
       return True
 Custom Sessions
 -----------------
 By default, the ``blink.auth.Auth`` class creates its own websession via its ``create_session`` method.  This is done when the class is initialized and is accessible via the ``Auth.session`` property. To override with a custom websession, the following code can accomplish that:
 .. code:: python
    from blinkpy.blinkpy import Blink
    from blinkpy.auth import Auth
    blink = Blink()
    blink.auth = Auth()
    blink.auth.session = YourCustomSession
 Custom HTTP requests
 ---------------------
 In addition to custom sessions, custom blink server requests can be performed.  This give you the ability to bypass the built-in ``Auth.query`` method.  It also allows flexibility by giving you the option to pass your own url, rather than be limited to what is currently implemented in the ``blinkpy.api`` module.
 **Send custom url**
 This prepares a standard "GET" request.
 .. code:: python
    from blinkpy.blinkpy import Blink
    from blinkpy.auth import Auth
    blink = Blink()
    blink.auth = Auth()
    url = some_api_endpoint_string
    request = blink.auth.prepare_request(url, blink.auth.header, None, "get")
    response = blink.auth.session.send(request)
 **Overload query method**
 Another option is to create your own ``Auth`` class with a custom ``query`` method to avoid the built-in response checking. This allows you to use the built in ``blinkpy.api`` endpoints, but also gives you flexibility to send your own urls.
 .. code:: python
    from blinkpy.blinkpy import Blink
    from blinkpy.auth import Auth
    from blinkpy import api
    class CustomAuth(Auth):
        def query(
            self,
            url=None,
            data=None,
            headers=self.header,
            reqtype="get",
            stream=False,
            json_resp=True,
            **kwargs
        ):
            req = self.prepare_request(url, headers, data, reqtype)
            return self.session.send(req, stream=stream)
    blink = blink.Blink()
    blink.auth = CustomAuth()
    # Send custom GET query
    response = blink.auth.query(url=some_custom_url)
    # Call built-in networks api endpoint
    response = api.request_networks(blink)
@@ -1,17 +0,0 @@
 .. _core_module:
 Blinkpy
 ----------------------
 .. automodule:: blinkpy.blinkpy
    :members:
 .. automodule:: blinkpy.sync_module
    :members:
 .. automodule:: blinkpy.camera
    :members:
 .. automodule:: blinkpy.helpers.util
    :members:
@@ -1,6 +0,0 @@
 API Reference
 ----------------------
 .. automodule:: blinkpy.api
    :members:
@@ -7,12 +7,16 @@ Welcome to blinkpy's documentation!
 ===================================
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
   :caption: Contents:
   :glob:
   README
-   api/*
+   advanced
   CONTRIBUTING
   modules/*
   CHANGES
 Indices and tables
 ==================
@@ -0,0 +1,41 @@
 .. _core_module:
 ===========================
 Blinkpy Library Reference
 ===========================
 blinkpy.py
 -----------
 .. automodule:: blinkpy.blinkpy
    :members:
 auth.py
 --------
 .. automodule:: blinkpy.auth
   :members:
 sync_module.py
 ----------------
 .. automodule:: blinkpy.sync_module
   :members:
 camera.py
 -----------
 .. automodule:: blinkpy.camera
   :members:
 api.py
 ---------
 .. automodule:: blinkpy.api
   :members:
 helpers/util.py
 ----------------
 .. automodule:: blinkpy.helpers.util
    :members: