From 68276e725277f83d1cf7ab164b6b59a7d5d3cf19 Mon Sep 17 00:00:00 2001
From: joncros <15827290+joncros@users.noreply.github.com>
Date: Mon, 7 Oct 2019 20:41:36 -0600
Subject: [PATCH] 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            |  2 ++
 docs/docs/job_registries.md | 45 +++++++++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)
 create mode 100644 docs/docs/job_registries.md

diff --git a/docs/_config.yml b/docs/_config.yml
index 0e2e73d5..89637cc5 100644
--- a/docs/_config.yml
+++ b/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
diff --git a/docs/docs/job_registries.md b/docs/docs/job_registries.md
new file mode 100644
index 00000000..729db10d
--- /dev/null
+++ b/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))
+```
\ No newline at end of file