From a07612f68757d5e79c60463de8e7bc54499b09fc Mon Sep 17 00:00:00 2001 From: Marcelo Moreira de Mello Date: Mon, 13 Mar 2017 07:09:41 -0400 Subject: [PATCH 1/2] Added basic structure for docs --- docs/Makefile | 20 +++++ docs/source/conf.py | 160 +++++++++++++++++++++++++++++++++++ docs/source/credits.rst | 9 ++ docs/source/how_to.rst | 91 ++++++++++++++++++++ docs/source/index.rst | 29 +++++++ docs/source/installation.rst | 13 +++ docs/source/source_code.rst | 36 ++++++++ 7 files changed, 358 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/source/conf.py create mode 100644 docs/source/credits.rst create mode 100644 docs/source/how_to.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/installation.rst create mode 100644 docs/source/source_code.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..6a7218da --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = PythonRingDoorBell +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) \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..823fa134 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,160 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# Python Ring Door Bell documentation build configuration file, created by +# sphinx-quickstart on Mon Mar 13 05:17:01 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# 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('../../ring_doorbell/')) + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# 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.ext.doctest', + 'sphinx.ext.viewcode', + 'sphinx.ext.githubpages'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'Python Ring Door Bell' +copyright = '2017, Marcelo Moreira de Mello' +author = 'Marcelo Moreira de Mello' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.1.1' +# The full version, including alpha/beta/rc tags. +release = '0.1.1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- 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 = 'alabaster' + +# 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 = {} + +# 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'] + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'PythonRingDoorBelldoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'PythonRingDoorBell.tex', 'Python Ring Door Bell Documentation', + 'Marcelo Moreira de Mello', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'pythonringdoorbell', 'Python Ring Door Bell Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'PythonRingDoorBell', 'Python Ring Door Bell Documentation', + author, 'PythonRingDoorBell', 'One line description of project.', + 'Miscellaneous'), +] + + + diff --git a/docs/source/credits.rst b/docs/source/credits.rst new file mode 100644 index 00000000..1191aedc --- /dev/null +++ b/docs/source/credits.rst @@ -0,0 +1,9 @@ +Credits && Thanks +----------------- + +* This project was inspired and based on https://github.com/jeroenmoors/php-ring-api. Many thanks @jeroenmoors. +* A guy named MadBagger at Prism19 for his initial research (http://www.prism19.com/doorbot/second-pass-and-comm-reversing/) +* The creators of mitmproxy (https://mitmproxy.org/) great http and https traffic inspector +* @mfussenegger for his post on mitmproxy and virtualbox https://zignar.net/2015/12/31/sniffing-vbox-traffic-mitmproxy/ +* To the project http://www.android-x86.org/ which allowed me to install Android on KVM. + diff --git a/docs/source/how_to.rst b/docs/source/how_to.rst new file mode 100644 index 00000000..bf8fce7c --- /dev/null +++ b/docs/source/how_to.rst @@ -0,0 +1,91 @@ +How To Use It +============= + +Initializing your Ring object +----------------------------- + +.. code-block:: python + + from ring_doorbell import Ring + myring = Ring('foo@bar', 'secret') + + myring.is_connected + True + + myring.has_subscription + True + + Chimes + ------ + +Listing devices linked to your account +------------------------------------------ + +.. code-block:: python + + # All devices + myring.devices + {'chimes': [], + 'doorbells': []} + + # All chimes + myring.chimes + [] + + # All door bells + myring.doorbells + [] + +Getting/setting attributes +-------------------------------- +.. code-block:: python + + for dev in list(myring.chimes + myring.doorbells): + + # refresh data + dev.update() + + print('Account ID: %s' % dev.account_id) + print('Address: %s' % dev.address) + print('Family: %s' % dev.family) + print('ID: %s' % dev.id) + print('Name: %s' % dev.name) + print('Timezone: %s' % dev.timezone) + + # setting dev volume + print('Volume: %s' % dev.volume) + dev.volume = 5 + print('Volume: %s' % dev.volume) + + # play dev test shound + if dev.family == 'chimes' + dev.test_sound + + +Showing door bell events +------------------------ +.. code-block:: python + + for doorbell in myring.doorbells: + + # listing the last 15 events of any kind + for event in doorbell.history(limit=15): + print('ID: %s' % event['id']) + print('Kind: %s' % event['kind']) + print('Answered: %s' % event['answered']) + print('When: %s' % event['created_at']) + print('--' * 50) + + # get a event list only the triggered by motion + events = doorbell.history(kind='motion') + + +Download the last video triggerd by ding +---------------------------------------- +.. code-block:: python + + doorbell = myring.doorbells[0] + doorbell.recording_download( + doorbell.history(limit=100, kind='ding')[0]['id'], + filename='/home/user/last_ding.mp4', + override=True) diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..f160cfee --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,29 @@ +================================================= +Python Ring Door Bell's documentation +================================================= + +Python Ring Door Bell is a library written in Python 2.7/3x +that exposes the Ring.com devices as Python objects. + + +.. note:: + Ring.com does not provide an official API. + The results of this project are merely from reverse engineering. + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + Installation + How to Use it + Source Code + Credits & Thanks + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` + +.. _Python Ring DoorBell: https://github.com/tchellomello/python-ring-doorbell diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 00000000..161c57fb --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,13 @@ +Installation +------------ + +.. code-block:: bash + + # Installing from PyPi + $ pip install ring_doorbell #python 2.7 + $ pip3 install ring_doorbell #python 3.x + + # Installing latest development + $ pip3 install \ + git+https://github.com/tchellomello/python-ring-doorbell@dev + diff --git a/docs/source/source_code.rst b/docs/source/source_code.rst new file mode 100644 index 00000000..221fbd38 --- /dev/null +++ b/docs/source/source_code.rst @@ -0,0 +1,36 @@ +Source code +----------- + + +class Ring +========== + +.. autoclass:: ring_doorbell.Ring + :members: + :undoc-members: + :show-inheritance: + +class RingGeneric +================= + +.. autoclass:: ring_doorbell.RingGeneric + :members: + :undoc-members: + :show-inheritance: + +class RingChime +=============== + +.. autoclass:: ring_doorbell.RingChime + :members: + :undoc-members: + :show-inheritance: + +class RingDoorBell +================== + +.. autoclass:: ring_doorbell.RingDoorBell + :members: + :undoc-members: + :show-inheritance: + :inherited-members: From 109de4c050a54484c9fc3e28d9a0c814fb325c0c Mon Sep 17 00:00:00 2001 From: Marcelo Moreira de Mello Date: Mon, 13 Mar 2017 07:11:52 -0400 Subject: [PATCH 2/2] fixed lint --- docs/source/conf.py | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 823fa134..b4bad9de 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -32,9 +32,9 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = ['sphinx.ext.autodoc', - 'sphinx.ext.doctest', - 'sphinx.ext.viewcode', - 'sphinx.ext.githubpages'] + 'sphinx.ext.doctest', + 'sphinx.ext.viewcode', + 'sphinx.ext.githubpages'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -130,7 +130,8 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'PythonRingDoorBell.tex', 'Python Ring Door Bell Documentation', + (master_doc, 'PythonRingDoorBell.tex', + 'Python Ring Door Bell Documentation', 'Marcelo Moreira de Mello', 'manual'), ] @@ -155,6 +156,3 @@ author, 'PythonRingDoorBell', 'One line description of project.', 'Miscellaneous'), ] - - -