add doc page for job registries (#1140)

* add doc page for job registries

* Use consistent language in registry type descriptions

* Correct usage of 'connection' parameter in Job Registry doc

docs/_config.yml

@@ -18,6 +18,8 @@ navigation:
     url: /docs/jobs/
   - text: Monitoring
     url: /docs/monitoring/
+  - text: Job Registries
+    url: /docs/job_registries/
   - text: Connections
     url: /docs/connections/
   - text: Exceptions

docs/docs/job_registries.md

@@ -0,0 +1,45 @@
+---
+title: "RQ: Job Registries"
+layout: docs
+---
+
+Each queue maintains a set of Job Registries:
+* `StartedJobRegistry` Holds currently executing jobs. Jobs are added right before they are 
+executed and removed right after completion (success or failure).
+* `FinishedJobRegistry` Holds successfully completed jobs.
+* `FailedJobRegistry` Holds jobs that have failed.
+* `DeferredJobRegistry` Holds deferred jobs (jobs that depend on another job and are waiting for that 
+job to finish).
+
+You can get the number of jobs in a registry, the ids of the jobs in the registry, and more. 
+Below is an example using a `StartedJobRegistry`.
+```python
+import time
+from redis import Redis
+from rq import Queue
+from rq.registry import StartedJobRegistry
+from somewhere import count_words_at_url
+
+conn = Redis()
+queue = Queue(connection=conn)
+job = queue.enqueue(count_words_at_url, 'http://nvie.com')
+
+# get StartedJobRegistry by queue
+registry = StartedJobRegistry(queue=queue)
+
+# or get StartedJobRegistry by queue name and connection
+registry2 = StartedJobRegistry(name='my_queue', connection=conn)
+
+# sleep for a moment while job is taken off the queue
+time.sleep(0.1)
+
+print('Queue associated with the registry: %s' % registry.get_queue())
+print('Number of jobs in registry %s' % registry.count)
+
+# get the list of ids for the jobs in the registry
+print('IDs in registry %s' % registry.get_job_ids())
+
+# test if a job is in the registry using the job instance or job id
+print('Job in registry %s' % (job in registry))
+print('Job in registry %s' % (job.id in registry))
+```