diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..298ea9e --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +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) \ No newline at end of file diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..fcdf971 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,40 @@ +API Reference +============= + +This sections has reference to all of the available classes, their +attributes and available methods. + +Discord OAuth2 Client +--------------------- + +.. autoclass:: flask_discord.DiscordOAuth2Session() + :members: + :inherited-members: + +.. autoclass:: flask_discord._http.DiscordOAuth2HttpClient() + :members: + :inherited-members: + + +Models +------ + +.. autoclass:: flask_discord.models.Guild() + :members: + :inherited-members: + +.. autoclass:: flask_discord.models.User() + :members: + :inherited-members: + +.. autoclass:: flask_discord.models.Bot() + :members: + :inherited-members: + +.. autoclass:: flask_discord.models.Integration() + :members: + :inherited-members: + +.. autoclass:: flask_discord.models.UserConnection() + :members: + :inherited-members: diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..90c4b42 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,64 @@ +# 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: +# http://www.sphinx-doc.org/en/master/config + +# -- 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 re +import sys +sys.path.insert(0, os.path.abspath('..')) +sys.path.append('../flask_discord/') + + +# -- Project information ----------------------------------------------------- + +project = 'Flask-Discord' +copyright = '2019, □ | The Cosmos' +author = '□ | The Cosmos' + +with open('../flask_discord/__init__.py') as f: + ver = re.search(r'^__version__\s*=\s*[\'"]([^\'"]*)[\'"]', f.read(), re.MULTILINE).group(1) +# The short X.Y version +version = ver +# The full version, including alpha/beta/rc tags +release = ver + + +# -- 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.ext.napoleon', + 'pallets_sphinx_themes', +] + +# 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 = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- 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 = 'flask' + +# 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'] diff --git a/docs/images/background.jpg b/docs/images/background.jpg new file mode 100644 index 0000000..d5e3b37 Binary files /dev/null and b/docs/images/background.jpg differ diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..d7f1711 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,37 @@ +.. Flask-Discord documentation master file, created by + sphinx-quickstart on Wed May 8 08:29:45 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Flask-Discord's documentation! +========================================= + +.. image:: /images/background.jpg + +Flask-Discord is an extension made for Flask which makes implementation of +Discord's OAuth2 API easier. + +**Features** + +- Clean object-oriented design. +- Covers most of the scopes provided by the API. +- Supports various discord models and objects. + + +Contents +-------- + +.. toctree:: + :maxdepth: 2 + + introduction + api + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/introduction.rst b/docs/introduction.rst new file mode 100644 index 0000000..0a112cf --- /dev/null +++ b/docs/introduction.rst @@ -0,0 +1,88 @@ +.. _intro: + + + +Introduction +============ + +Flask-Discord is an extension for Flask - Python web framework which +makes easy implementation of Discord OAuth2 API. After creating a discord +client object, one can easily request authorization and hence any of the +resources provided by the discord OAuth2 API under the available scope +permissions. + +Requirements +------------ + +This extensions requires ``Flask`` installed. Python version can be chosen +as per ``Flask`` requirements. + +It also requires another library ``requests_oauthlib`` to create OAuth2 sessions +to discord. + +Installing +---------- + +You can install Flask-Discord directly from PyPI using PIP and following command +in shell or command prompt: :: + + python3 -m pip install -U Flask-Discord + +You can also install the latest development version (**maybe unstable/broken**) by +using following command: :: + + python3 -m pip install -U git+https://github.com/thec0sm0s/Flask-Discord.git + + +Basic Usage +----------- +Here is a simple example to get users authorization token using OAuth2 and use it +in exchange for fetching user's details and display them on web page. + + +.. code-block:: python3 + + from flask import Flask, redirect, url_for + from flask_discord import DiscordOAuth2Session + + CONFIGS = { + "client_id": 9999999999, + "client_secret": "your client secret", + "redirect_uri": "default redirect uri", + } + + app = Flask(__name__) + app.secret_key = "random bytes representing flask secret key" + discord = DiscordOAuth2Session(**CONFIGS) + + + @app.route("/login") + def login(): + return discord.create_session() + + + @app.route("/callback") + def callback(): + discord.callback() + return redirect(url_for(".me")) + + + @app.route("/me") + def me(): + user = discord.fetch_user() + return f""" + + + {user.name} + + + + + + + """ + + + + if __name__ == "__main__": + app.run() \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..7893348 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the 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 diff --git a/flask_discord/__init__.py b/flask_discord/__init__.py index 273e082..1c061e3 100644 --- a/flask_discord/__init__.py +++ b/flask_discord/__init__.py @@ -6,4 +6,4 @@ __all__ = [ ] -__version__ = "0.0.1" +__version__ = "0.0.2" diff --git a/flask_discord/models/__init__.py b/flask_discord/models/__init__.py index 1c1d1e8..6cc439f 100644 --- a/flask_discord/models/__init__.py +++ b/flask_discord/models/__init__.py @@ -1,6 +1,6 @@ from .guild import Guild from .user import User, Bot -from .connections import UserConnection +from .connections import UserConnection, Integration __all__ = [ @@ -8,4 +8,5 @@ __all__ = [ "User", "Bot", "UserConnection", + "Integration", ] diff --git a/setup.py b/setup.py index 3f35352..714d423 100644 --- a/setup.py +++ b/setup.py @@ -37,10 +37,10 @@ setup( name='Flask-Discord', version='0.0.1', url='https://github.com/thec0sm0s/Flask-Discord', - license='BSD', + license='MIT', author='□ | The Cosmos', author_email='deepakrajko14@gmail.com', - description='', + description='Discord OAuth2 extension for Flask.', long_description=__doc__, packages=['flask_discord'], zip_safe=False,