Add docs with sphinx (#25)

* 📚 Replace pdoc3 with sphinx docs

* 👀 Add hint for github to ignore kekyll rendering

* 🎨 Remove warning

* 📚 Add redirect to sphinx custom html dump. Reference: sphinx-doc/sphinx#3382

* 🔧

* 🔧 Unignore docs artifacts

* 📚

* 🚀 Update docs target

* 🔧

* 🎨 Style Changes

.gitignore

@@ -69,9 +69,6 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
-docs/_build/
-
 # PyBuilder
 target/
 

Makefile

@@ -19,9 +19,6 @@ checks: build style test
 	@echo "✔ All CI Checks Passed"
 
 docs:
-	pdoc3 src/slackify \
-	--config 'search_query="inurl:github.com/Ambro17/slackify  site:ambro17.github.io/slackify"' \
-	--config 'git_link_template="https://github.com/Ambro17/slackify/blob/master/{path}#L{start_line}-L{end_line}"' \
-	--template-dir 'templates' \
-	--html -o docs --force && \
-	cp -r docs/slackify/* docs && rm -rf docs/slackify
+	cd docs && \
+	make html && \
+	cd -

README.md

@@ -305,7 +305,7 @@ If you are a user of pytest, this idea is similar to pytest fixtures
 See [examples/injection.py](examples/injection.py) for the full example
 
 
-## Usage as a Blueprint
+## Blueprint Support
 If you already have a Flask app, you can attach
 flask functionality _slackifying_ your blueprint
 ```python
@@ -334,4 +334,4 @@ def create_app():
 > Note: You must import Blueprint from slackify instead of flask to get it working
 
 ## Dependencies
-This projects uses `Flask` as the web server and `slackclient` (_The official python slack client_) as slack's API wrapper
+This projects uses `Flask` as the web server and `slackclient` (_The official python slack client_) as slack's API wrapper. It also uses `pyee` for async handling of events

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+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)

docs/_build/html/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: f3b71497ca8797d0da9b3dcd52e3d342
+tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_build/html/_sources/api_reference.rst.txt

@@ -0,0 +1,7 @@
+##################
+API Reference
+##################
+
+.. automodule:: slackify
+    :members:
+    :undoc-members: 

docs/_build/html/_sources/examples.rst.txt

@@ -0,0 +1,86 @@
+########
+Examples
+########
+
+As you navigate through `Slack Api Docs
+<https://api.slack.com/>`_. you may find yourself with 20+ tabs open 
+and still no clue on how to accomplish what you want.
+
+If that's your case, this section might help you getting started quickly
+
+There are examples of the most frequent use cases. Ranging from a bot
+with just a few commands, to a full workflow of registration and callbacks
+on userinput.
+
+Examples:
+
+- :ref:`Commands`
+- :ref:`Interactive Actions`
+- :ref:`Modals/Views<Modals (Views)>`
+- :ref:`Global/Message Shortcuts<Shortcuts>`
+- :ref:`Event Hooks`
+- :ref:`Message Hooks`
+- :ref:`Home tab personalization<Home Tab>`
+- :ref:`Async Tasks`
+- :ref:`Usage as a Blueprint<As a Blueprint>`
+- :ref:`Arguments Injection`
+- :ref:`Block Messages`
+- :ref:`Full example`
+
+
+Commands
+--------
+.. literalinclude:: ../examples/commands.py
+
+Interactive Actions
+-------------------
+.. literalinclude:: ../examples/actions.py
+
+
+Modals (Views)
+-------------------
+.. literalinclude:: ../examples/views.py
+
+
+Shortcuts
+----------------------------
+.. literalinclude:: ../examples/shortcuts.py
+
+Event Hooks
+----------------------------
+.. literalinclude:: ../examples/events.py
+
+
+Message Hooks
+----------------------------
+.. literalinclude:: ../examples/message.py
+
+
+Home Tab
+----------------------------
+.. literalinclude:: ../examples/home_tab.py
+
+
+Async tasks
+----------------------------
+.. literalinclude:: ../examples/async_task.py
+
+
+As a Blueprint
+----------------------------
+.. literalinclude:: ../examples/as_blueprint.py
+
+
+Arguments Injection
+----------------------------
+.. literalinclude:: ../examples/injection.py
+
+
+Block Messages
+----------------------------
+.. literalinclude:: ../examples/using_blocks.py
+
+
+Full example
+----------------------------
+.. literalinclude:: ../examples/full.py

docs/_build/html/_sources/getting_started.rst.txt

@@ -0,0 +1,98 @@
+###############
+Getting Started
+###############
+
+Installation
+============
+The first step to use slackify is to install it inside your virtualenv
+
+.. code-block:: shell
+
+    python3 -m pip install slackify
+
+
+.. note:: Slackify requires python3.6 or higher to run
+
+
+Running the bot
+===============
+To run the bot create a file named :code:`app.py` with the following content
+
+.. code-block:: python
+
+    from flask import Flask
+    from slackify import Slackify, reply_text
+
+    app = Flask(__name__)
+    slackify = Slackify(app=app)
+
+
+    @slackify.command
+    def hello():
+        return reply_text('Hello from Slackify!')
+
+
+    if __name__ == '__main__':
+        app.run(host='0.0.0.0', port=5000)
+
+Then run the server with
+
+.. code-block:: shell
+
+    python3 app.py
+
+What happened here?
+We created a :code:`Flask` app, then we passed it to Slackify to get a 
+slackified app.
+Then we decorated a function with :code:`@slackify.command` to register it
+as the function that should be called when slack user invokes :code:`/hello`
+
+Let's check if it works, type :code:`http://localhost:5050/hello` in your browser.
+You should see the following response:
+
+.. code-block:: json
+
+    {
+        "text": "Hello from Slackify!"
+    }
+
+Great! Now our bot is fully operational, but we must connect it to slack so 
+users other than ourselves can start using it. Let's do that
+
+
+Connecting to slack
+===================
+
+Slack requires a publicly available url for our bot,
+while developing it might get tedious to upload every change to a public server
+just to test if everything works.
+To overcome this we can use ngrok to create an https tunnel from a 
+public, temporal url, to your localhost server.
+
+That way slack has the url it needs, but we can still quickly make
+changes to our bot to change its behaviour.
+
+To connect our bot we must complete these 2 Steps:
+
+1. Install ngrok
+2. Create slack app pointing to our ngrok's public url
+
+Install ngrok
+-------------
+
+Go to https://ngrok.com/download and follow the instructions
+Then run :code:`ngrok http 5000`. This will expose an http url, and redirect
+all requests to localhost on port 5000.
+
+Create a Slack App
+------------------
+Go to https://api.slack.com/apps?new_app=1 and create a new app.
+Enable :code:`Bots` feature and install it to your workspace, then 
+save your `Bot User OAuth Access Token` that we will need later.
+Enable :code:`Slash Commands` feature and create a new command 
+:code:`hello` with the url set to ngrok's http url of step #1
+
+
+.. note:: 
+    It might ask you to login to your workspace before creating an app.
+    After you login, follow that link and you should be able to create it

docs/_build/html/_sources/index.rst.txt

@@ -0,0 +1,30 @@
+Welcome to Slackify's documentation!
+====================================
+:code:`Slackify` provides a declarative API to register handlers for Slack
+
+- Commands
+- Actions
+- Events
+- Shorcuts
+- Modals
+- Messages
+- And more!
+
+Its main focus is to make the task of developing slack bots **fun and fast**.
+
+That's why it tries to hide all implementation details and offer a clean *flask-like* decorator syntax.
+Hopefully, this will allow you to focus on the workflows you want to support,
+instead of struggling with routing, endpoint or payload details.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Content
+
+   getting_started
+   api_reference
+   examples
+
+Search docs
+==================
+
+* :ref:`search`