first stab at sphinx docs (#154)

* test docs

* Create placeholder

* fixed typo

* updated image

* added tests

* removed tz for ci

* first stab at sphinx docs. added tox

* updated gitlab

.github/workflows/main.yml

@@ -16,9 +16,8 @@ jobs:
 
       - name: build docs
         run: |
-          pip install sphinx Pygments furo sphinx-copybutton sphinx-inline-tabs myst-parser colorama sphinx-panels
-          cd docs
-          sphinx-build -E -b html . _build
+          pip install tox
+          tox -e docs
 
       # Runs a set of commands using the runners shell
       - name: publish

README.rst

@@ -19,163 +19,12 @@ You can install Flask-APScheduler via Python Package Index (PyPI_),::
 
     pip install Flask-APScheduler
 
-Documentation
-===============
-
-Setup
------
-
-* Create a flask application. For an example, see `this tutorial <https://pythonspot.com/flask-web-app-with-python/>`_
-* Import and initialize ``Flask-APScheduler``
-* Set any configuration needed
-
-A basic example will looks like this.
-
-.. code-block:: python
-
-    from flask import Flask
-    # import Flask-APScheduler
-    from flask_apscheduler import APScheduler
-
-    # set configuration values
-    class Config(object):
-        SCHEDULER_API_ENABLED = True
-
-    # create app
-    app = Flask(__name__)
-    app.config.from_object(Config())
-
-    # initialize scheduler
-    scheduler = APScheduler()
-    # if you don't wanna use a config, you can set options here:
-    # scheduler.api_enabled = True
-    scheduler.init_app(app)
-    scheduler.start()
-
-
-    if __name__ == '__main__':
-        app.run()
-
-Adding Jobs
------------
-
-Jobs can be added to the scheduler when the app starts. They are created in decorated functions, which should be imported before ``app.run()`` is called.
-
-.. code-block:: python
-
-    # interval example
-    @scheduler.task('interval', id='do_job_1', seconds=30, misfire_grace_time=900)
-    def job1():
-        print('Job 1 executed')
-
-
-    # cron examples
-    @scheduler.task('cron', id='do_job_2', minute='*')
-    def job2():
-        print('Job 2 executed')
-
-
-    @scheduler.task('cron', id='do_job_3', week='*', day_of_week='sun')
-    def job3():
-        print('Job 3 executed')
-
-
-Jobs can also be added after you app is running
-
-.. code-block:: python
-
-    scheduler.add_job(**args)
-
-If you wish to use anything from your Flask app context inside the job you can use something like this
-
-.. code-block:: python
-
-    def blah():
-        with scheduler.app.app_context():
-            # do stuff
-
-Logging
--------
 
-All scheduler events can be used to trigger logging functions. See `APScheduler <https://apscheduler.readthedocs.io/en/stable/userguide.html#scheduler-events>`_ for a list of available events.
 
-If you are using your Flask app context inside of a function triggered by a scheduler event can include something like this
-
-.. code-block:: python
-
-    def blah():
-        with scheduler.app.app_context():
-            # do stuff
-
-    scheduler.add_listener(blah, EVENT_JOB_EXECUTED | EVENT_JOB_ERROR)
-
-
-API
----
-
-Flask-APScheduler comes with a build-in API. This can be enabled/disabled in your flask configuration.
-
-.. code-block:: python
-
-    SCHEDULER_API_ENABLED: True
-
-
-- /scheduler [GET] > returns basic information about the webapp
-- /scheduler/jobs [POST json job data] > adds a job to the scheduler
-- /scheduler/jobs/<job_id> [GET] > returns json of job details
-- /scheduler/jobs [GET] > returns json with details of all jobs
-- /scheduler/jobs/<job_id> [DELETE] > deletes job from scheduler
-- /scheduler/jobs/<job_id> [PATCH json job data] > updates an already existing job
-- /scheduler/jobs/<job_id>/pause [POST] > pauses a job, returns json of job details
-- /scheduler/jobs/<job_id>/resume [POST] > resumes a job, returns json of job details
-- /scheduler/jobs/<job_id>/run [POST] > runs a job now, returns json of job details
-
-
-Scheduler
----------
-
-Other commands can be passed to the scheduler and are rather self explainatory:
-
-- scheduler.start()
-- scheduler.shutdown()
-- scheduler.pause() > stops any job from starting. Already running jobs not affected.
-- scheduler.resume() > allows scheduled jobs to begin running.
-- scheduler.add_listener(<callback function>,<event>)
-- scheduler.remove_listener(<callback function>)
-- scheduler.add_job(<id>,<function>, **kwargs)
-- scheduler.remove_job(<id>, **<jobstore>)
-- scheduler.remove_all_jobs(**<jobstore>)
-- scheduler.get_job(<id>,**<jobstore>)
-- scheduler.modify_job(<id>,**<jobstore>, **kwargs)
-- scheduler.pause_job(<id>, **<jobstore>)
-- scheduler.resume_job(<id>, **<jobstore>)
-- scheduler.run_job(<id>, **<jobstore>)
-- scheduler.authenticate(<function>)
-
-
-Configuration
--------------
-
-Configuration options specific to ``Flask-APScheduler``:
-
-.. code-block:: python
-
-    SCHEDULER_API_ENABLED: <True or False>
-
-Other configuration options are included from `APScheduler <https://apscheduler.readthedocs.io/en/stable/userguide.html#configuring-the-scheduler>`_
-
-
-Tips
-----
-
-When running Flask-APScheduler on a wsgi process only **1** worker should be enabled. APScheduler 3.0 will only work with a single worker process. Jobstores cannot be shared among multiple schedulers.
-
-See `APScheduler's <https://apscheduler.readthedocs.io/en/stable/>`_ documentation for further help.
-
-Take a look at the examples_ to see how it works.
-
-Also take a look at `COMMON-ISSUES.md <https://github.com/viniciuschiele/flask-apscheduler/blob/master/COMMON-ISSUES.md>`_ for help.
+Documentation
+===============
 
+`See Flask APSchedulers Documentation. <https://viniciuschiele.github.io/flask-apscheduler/>`_
 
 
 Feedback

dev-requirements.txt

@@ -0,0 +1,6 @@
+reformat
+flake8
+flake8-bandit
+pygments
+black
+pylint

docs-requirements.txt

@@ -0,0 +1,8 @@
+sphinx
+Pygments
+furo
+sphinx-copybutton
+sphinx-inline-tabs
+myst-parser
+colorama
+sphinx-panels

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/conf.py

@@ -0,0 +1,56 @@
+# flake8: noqa
+# pylint: skip-file
+# Configuration file for the Sphinx documentation builder.
+
+#
+# -- Path setup --------------------------------------------------------------
+#
+
+import sys
+from pathlib import Path
+
+sys.path.append(str(Path(__file__).parent))
+
+
+#
+# -- Project information -----------------------------------------------------
+#
+
+project = "Flask APScheduler"
+copyright = "2015, Vinicius Chiele"
+
+
+#
+# -- General configuration ---------------------------------------------------
+#
+
+extensions = [
+    "sphinx.ext.extlinks",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.todo",
+    "sphinx_copybutton",
+    "sphinx_inline_tabs",
+    "sphinx_panels",
+    "myst_parser",
+]
+
+templates_path = ["_templates"]
+
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "venv"]
+
+pygments_style = "colorful"
+
+#
+# -- Options for HTML output -------------------------------------------------
+#
+
+html_theme = "furo"
+html_title = "Flask APScheduler"
+#html_logo = "images/icon-512x512.png"
+#html_favicon = "images/favicon.ico"
+
+html_theme_options = {
+    #"sidebar_hide_name": True,
+}

docs/index.rst

@@ -0,0 +1,22 @@
+Flask APScheduler Docs
+===========================
+
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :titlesonly:
+
+   Overview <self>
+   rst/install.rst
+   rst/configuration.rst
+   rst/usage.rst
+   rst/logging.rst
+   rst/api.rst
+   rst/examples.rst
+   rst/tips.rst
+
+
+
+.. include:: rst/readme.rst
+