Added baseline for sphinx documentation and on2FACode event

The docs are still very WIP, but they should be functional. Just
execute `make html` in the docs folder, and you should be able to
navigate to `/docs/_build/html` and view it in your browser

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = python3.6 -msphinx
+SPHINXPROJ    = fbchat
+SOURCEDIR     = .
+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)

docs/_static/license.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="80" height="20"><linearGradient id="b" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="a"><rect width="80" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#a)"><path fill="#555" d="M0 0h47v20H0z"/><path fill="#007ec6" d="M47 0h33v20H47z"/><path fill="url(#b)" d="M0 0h80v20H0z"/></g><g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11"><text x="23.5" y="15" fill="#010101" fill-opacity=".3">license</text><text x="23.5" y="14">license</text><text x="62.5" y="15" fill="#010101" fill-opacity=".3">BSD</text><text x="62.5" y="14">BSD</text></g></svg>

docs/_static/python-versions.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="154" height="20"><linearGradient id="b" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="a"><rect width="154" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#a)"><path fill="#555" d="M0 0h49v20H0z"/><path fill="#007ec6" d="M49 0h105v20H49z"/><path fill="url(#b)" d="M0 0h154v20H0z"/></g><g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11"><text x="24.5" y="15" fill="#010101" fill-opacity=".3">python</text><text x="24.5" y="14">python</text><text x="100.5" y="15" fill="#010101" fill-opacity=".3">2.7, 3.4, 3.5, 3.6</text><text x="100.5" y="14">2.7, 3.4, 3.5, 3.6</text></g></svg>

docs/_templates/layout.html

@@ -0,0 +1,26 @@
+{% extends '!layout.html' %}
+
+{% block extrahead %}
+<script async defer src="https://buttons.github.io/buttons.js"></script>
+<!-- Alabaster (krTheme++) Hacks, modified version of Kenneth Reitz' https://github.com/kennethreitz/requests/blob/master/docs/_templates/hacks.html -->
+<style type="text/css">
+    /* Rezzy requires precise alignment. */
+    img.logo {margin-left: -20px!important;}
+    /* "Quick Search" should be capitalized. */
+    div#searchbox h3 {text-transform: capitalize;}
+    /* Go button should be behind input field */
+    div.sphinxsidebar div#searchbox input[type="text"] {width: 160px}
+    div#searchbox form div {display: inline-block;}
+    /* Make the document a little wider, less code is cut-off. */
+    div.document {width: 1008px;}
+    /* Much-improved spacing around code blocks. */
+    div.highlight pre {padding: 11px 14px;}
+    /* Remain Responsive! */
+    @media screen and (max-width: 1008px) {
+        div.sphinxsidebar {display: none;}
+        div.document {width: 100%!important;}
+        /* Have code blocks escape the document right-margin. */
+        div.highlight pre {margin-right: -30px;}
+    }
+</style>
+{% endblock %}

docs/_templates/sidebar.html

@@ -0,0 +1,13 @@
+<h3>
+    <a href="{{ pathto(master_doc) }}">{{ _(project) }}</a>
+</h3>
+
+<p>
+    <a class="github-button" href="https://github.com/carpedm20/fbchat" data-size="large" data-show-count="true" aria-label="Star carpedm20/fbchat on GitHub">Star</a>
+</p>
+
+<p>
+    {{ _(shorttitle) }}
+</p>
+
+{{ toctree() }}

docs/api.rst

@@ -0,0 +1,46 @@
+.. module:: fbchat
+.. highlight:: python
+.. _api:
+
+Full API
+========
+
+If you are looking for information on a specific function, class, or method, this part of the documentation is for you.
+
+
+.. _api_client:
+
+Client
+------
+
+.. todo::
+    Write introduction text about `Client`, and add documentation for all events
+
+.. autoclass:: Client(email, password, user_agent=None, max_retries=5, session_cookies=None, logging_level=logging.INFO, set_default_events=True)
+    :members:
+
+    .. automethod:: sendRemoteImage(image_url, message=None, thread_id=None, thread_type=ThreadType.USER)
+    .. automethod:: sendLocalImage(image_path, message=None, thread_id=None, thread_type=ThreadType.USER)
+
+
+.. _api_models:
+
+Models
+------
+
+These models are used in various functions, both as inputs and return values.
+A good tip is to write ``from fbchat.models import *`` at the start of your source, so you can use these models freely
+
+.. automodule:: fbchat.models
+    :members:
+
+
+.. _api_utils:
+
+Utils
+-----
+
+These functions and values are used internally by fbchat, and are subject to change. Do **NOT** rely on these to be backwards compatible!
+
+.. automodule:: fbchat.utils
+    :members:

docs/conf.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# fbchat documentation build configuration file, created by
+# sphinx-quickstart on Thu May 25 15:43: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('..'))
+
+import fbchat
+import tests
+from fbchat import __copyright__, __author__, __version__, __description__
+
+
+# -- 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.intersphinx',
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode'
+]
+
+# 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 = 'fbchat'
+title = 'fbchat Documentation'
+copyright = __copyright__
+author = __author__
+description = __description__
+
+# 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 = __version__
+# The full version, including alpha/beta/rc tags.
+release = __version__
+
+# 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 = ['_build', 'Thumbs.db', '.DS_Store']
+
+# 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 = True
+
+
+# -- 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 = project + 'doc'
+
+
+# -- 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, project + '.tex', title,
+     author, '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, project, title,
+     [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, project, title,
+     author, project, description,
+     'Miscellaneous'),
+]
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {'https://docs.python.org/3/': None}
+
+
+
+add_function_parentheses = False
+
+html_theme_options = {
+    'show_powered_by': False,
+    'github_user': 'carpedm20',
+    'github_repo': project,
+    'github_banner': True,
+    'show_related': False
+}
+
+html_sidebars = {
+    '**': ['sidebar.html', 'searchbox.html']
+}
+
+html_show_sphinx = False
+html_show_sourcelink = False
+autoclass_content = 'init'
+html_short_title = description

docs/examples.rst

@@ -0,0 +1,52 @@
+.. highlight:: python
+.. _examples:
+
+Examples
+========
+
+These are a few examples on how to use `fbchat`. Remember to swap out `<email>` and `<password>` for your email and password
+
+
+Sending messages
+----------------
+
+This will send one of each message type to the specified thread
+
+.. literalinclude:: ../examples/send.py
+    :language: python
+
+
+Getting information
+-------------------
+
+This will show the different ways of fetching information about users and threads
+
+.. literalinclude:: ../examples/get.py
+    :language: python
+
+
+Echobot
+-------
+
+This will reply to any message with the same message
+
+.. literalinclude:: ../examples/echobot.py
+    :language: python
+
+
+Remove bot
+----------
+
+This will remove a user from a group if they write the message `Remove me!`
+
+.. literalinclude:: ../examples/removebot.py
+    :language: python
+
+
+"Keep it"-bot
+-------------
+
+This will prevent chat color, emoji, nicknames and chat name from being changed. It will also prevent people from being added and removed
+
+.. literalinclude:: ../examples/keepbot.py
+    :language: python

docs/index.rst

@@ -0,0 +1,51 @@
+.. highlight:: python
+.. fbchat documentation master file, created by
+   sphinx-quickstart on Thu May 25 15:43:01 2017.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+.. This documentation's layout is heavily inspired by requests' layout: https://requests.readthedocs.io
+   Some documentation is also partially copied from facebook-chat-api: https://github.com/Schmavery/facebook-chat-api
+
+fbchat: Facebook Chat (Messenger) for Python
+============================================
+
+Release v\ |version|. (:ref:`install`)
+
+.. generated with: https://img.shields.io/badge/license-BSD-blue.svg
+
+.. image:: /_static/license.svg
+    :target: https://github.com/carpedm20/fbchat/blob/master/LICENSE.txt
+
+.. generated with: https://img.shields.io/badge/python-2.7%2C%203.4%2C%203.5%2C%203.6-blue.svg
+
+.. image:: /_static/python-versions.svg
+    :target: https://pypi.python.org/pypi/fbchat
+
+Facebook Chat (`Messenger <https://www.facebook.com/messages/>`__) for Python. This project was inspired by `facebook-chat-api <https://github.com/Schmavery/facebook-chat-api>`__.
+
+**No XMPP or API key is needed**. Just use your email and password.
+
+Currently `fbchat` support Python 2.7, 3.4, 3.5 and 3.6:
+
+`fbchat` works by emulating the browser. This means doing the exact same GET/POST requests and tricking Facebook into thinking we're accessing the website normally.
+Because we're doing it this way, this API requires the credentials of a Facebook account.
+
+.. warning::
+    We are not responsible if your account gets banned for spammy activities such as sending lots of messages to people you don't know, sending messages very quickly, sending spammy looking URLs, logging in and out very quickly... Be responsible Facebook citizens.
+
+.. note::
+    Facebook now has an `official API <https://developers.facebook.com/docs/messenger-platform>`_ for chat bots, so if you're familiar with node.js, this might be what you're looking for.
+
+Overview
+--------
+
+.. toctree::
+    :maxdepth: 2
+
+    install
+    intro
+    examples
+    testing
+    api
+    todo

docs/install.rst

@@ -0,0 +1,36 @@
+.. highlight:: sh
+.. _install:
+
+Installation
+============
+
+Pip Install fbchat
+------------------
+
+To install fbchat, run this command::
+
+    $ pip install fbchat
+
+If you don't have `pip <https://pip.pypa.io>`_ installed,
+`this Python installation guide <http://docs.python-guide.org/en/latest/starting/installation/>`_
+can guide you through the process.
+
+Get the Source Code
+-------------------
+
+fbchat is developed on GitHub, where the code is
+`always available <https://github.com/carpedm20/fbchat>`_.
+
+You can either clone the public repository::
+
+    $ git clone git://github.com/carpedm20/fbchat.git
+
+Or, download a `tarball <https://github.com/carpedm20/fbchat/tarball/master>`_::
+
+    $ curl -OL https://github.com/carpedm20/fbchat/tarball/master
+      # optionally, zipball is also available (for Windows users).
+
+Once you have a copy of the source, you can embed it in your own Python
+package, or install it into your site-packages easily::
+
+    $ python setup.py install

docs/intro.rst

@@ -0,0 +1,86 @@
+.. highlight:: python
+.. _intro:
+
+Introduction
+============
+
+.. todo::
+    Make a general introduction to `fbchat`
+
+
+.. _intro_logging_in:
+
+Logging in
+----------
+
+.. todo::
+    Write something about logging in, logging out, checking login, 2FA and the event `on2FACode`, here
+
+
+.. _intro_sessions:
+
+Sessions
+--------
+
+.. todo::
+    Make an introduction to and show example usage of sessions
+
+
+.. _intro_sending:
+
+Sending messages
+----------------
+
+.. todo::
+    Make an introduction to and show example usage of how you send information
+
+.. literalinclude:: ../examples/send.py
+    :language: python
+
+
+.. _intro_fetching:
+
+Fetching information
+--------------------
+
+.. todo::
+    Make an introduction to and show example usage of fetching information
+
+.. literalinclude:: ../examples/get.py
+    :language: python
+
+
+.. _intro_thread_id:
+
+Thread ids
+----------
+
+.. todo::
+    Make an introduction to and show example usage of thread ids
+
+
+.. _intro_thread_type:
+
+Thread types
+------------
+
+.. todo::
+    Make an introduction to and show example usage of thread types
+
+
+.. _intro_message_ids:
+
+Message ids
+-----------
+
+.. todo::
+    Make an introduction to and show example usage of message ids
+
+
+.. _intro_events:
+
+Events
+------
+
+.. todo::
+    Make an introduction to and show example usage of the event system

docs/make.bat

@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=python3.6 -msphinx
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+set SPHINXPROJ=fbchat
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The Sphinx module was not found. Make sure you have Sphinx installed,
+	echo.then set the SPHINXBUILD environment variable to point to the full
+	echo.path of the 'sphinx-build' executable. Alternatively you may add the
+	echo.Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

docs/testing.rst

@@ -0,0 +1,28 @@
+.. highlight:: sh
+.. _testing:
+
+Testing
+=======
+
+To use these tests copy ``tests/data.json`` to ``tests/my_data.json`` or type the information manually in the terminal prompts.
+
+- email: Your (or a test user's) email / phone number
+- password: Your (or a test user's) password
+- group_thread_id: A test group that will be used to test group functionality
+- user_thread_id: A person that will be used to test kick/add functionality (This user should be in the group)
+
+Please remember to test all supported python versions.
+If you've made any changes to the 2FA functionality, test it with a 2FA enabled account.
+
+If you only want to execute specific tests, pass the function names in the commandline (not including the `test_` prefix). Example::
+
+    $ python tests.py sendMessage sessions sendEmoji
+
+.. warning::
+
+    Do not execute the full set of tests in too quick succession. This can get your account temporarily blocked for spam!
+    (You should execute the script at max about 10 times a day)
+
+.. automodule:: tests
+    :members: TestFbchat
+    :undoc-members: TestFbchat

docs/todo.rst

@@ -0,0 +1,22 @@
+.. highlight:: python
+.. _todo:
+
+Todo
+====
+
+
+Functionality
+-------------
+
+- Implement Client.changeThreadEmoji
+- Implement Client.changeNickname
+- Implement Client.searchForThread
+    - This will use the graphql request API
+- Implement Client.searchForMessage
+    - This will use the graphql request API
+
+
+Documentation
+-------------
+
+.. todolist::