Documented the migration and the scheduler statesv3.2.0

3 files changed, 22 insertions, 10 deletions

diff --git a/apscheduler/schedulers/base.py b/apscheduler/schedulers/base.py
index 2261bd9..72e3c39 100644
--- a/apscheduler/schedulers/base.py
+++ b/apscheduler/schedulers/base.py
@@ -26,8 +26,11 @@ from apscheduler.events import (
     EVENT_JOB_ADDED, EVENT_EXECUTOR_ADDED, EVENT_EXECUTOR_REMOVED, EVENT_ALL_JOBS_REMOVED,
     EVENT_JOB_SUBMITTED, EVENT_JOB_MAX_INSTANCES, EVENT_SCHEDULER_RESUMED, EVENT_SCHEDULER_PAUSED)
 
+#: constant indicating a scheduler's stopped state
 STATE_STOPPED = 0
+#: constant indicating a scheduler's running state (started and processing jobs)
 STATE_RUNNING = 1
+#: constant indicating a scheduler's paused state (started but not processing jobs)
 STATE_PAUSED = 2
 
 
@@ -46,6 +49,9 @@ class BaseScheduler(six.with_metaclass(ABCMeta)):
     :param dict executors: a dictionary of executor alias -> executor instance or configuration
         dict
 
+    :ivar int state: current running state of the scheduler (one of the following constants from
+        ``apscheduler.schedulers.base``: ``STATE_STOPPED``, ``STATE_RUNNING``, ``STATE_PAUSED``)
+
     .. seealso:: :ref:`scheduler-config`
     """
 
@@ -208,12 +214,12 @@ class BaseScheduler(six.with_metaclass(ABCMeta)):
     @property
     def running(self):
         """
-        Return ``True`` if the scheduler has been started and is processing jobs normally.
+        Return ``True`` if the scheduler has been started.
 
-        This is a shortcut for ``scheduler.state == STATE_RUNNING``.
+        This is a shortcut for ``scheduler.state != STATE_STOPPED``.
 
         """
-        return self.state == STATE_RUNNING
+        return self.state != STATE_STOPPED
 
     def add_executor(self, executor, alias='default', **executor_opts):
         """
diff --git a/docs/migration.rst b/docs/migration.rst
index ed4f93f..d7bc201 100644
--- a/docs/migration.rst
+++ b/docs/migration.rst
@@ -2,8 +2,18 @@
 Migrating from previous versions of APScheduler
 ###############################################
 
-From v2.x to 3.0
-================
+From v3.0 to v3.2
+=================
+
+Prior to v3.1, the scheduler inadvertently exposed the ability to fetch and manipulate jobs before
+the scheduler had been started. The scheduler now requires you to call ``scheduler.start()`` before
+attempting to access any of the jobs in the job stores. To ensure that no old jobs are mistakenly
+executed, you can start the scheduler in paused mode (``scheduler.start(paused=True)``) (introduced
+in v3.2) to avoid any premature job processing.
+
+
+From v2.x to v3.0
+=================
 
 The 3.0 series is API incompatible with previous releases due to a design overhaul.
 
diff --git a/docs/modules/schedulers/base.rst b/docs/modules/schedulers/base.rst
index 7f6c686..fecacca 100644
--- a/docs/modules/schedulers/base.rst
+++ b/docs/modules/schedulers/base.rst
@@ -2,9 +2,5 @@
 ==================================
 
 .. automodule:: apscheduler.schedulers.base
-
-API
----
-
-.. autoclass:: BaseScheduler
     :members:
+    :member-order: bysource