include legacy docs

Author: mrlevitas

docs/conf.py

@@ -38,7 +38,7 @@
 master_doc = "index"
 
 # General information about the project.
-project = "Experiments"
+project = "Experiments.py"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -67,7 +67,7 @@
 # which templates to put in the sidebar.  we're just removing the relations
 # section from the defaults here, that's "next article" and "previous article"
 html_sidebars = {
-    "**": []
+    "**": ["about.html", "searchbox.html", "navigation.html"]
 }
 
 html_theme_options = {

docs/index.rst

@@ -1,4 +1,6 @@
-``reddit_experiments``
+ .. _reddit_decider:
+
+``reddit_decider``
 ===============================
 
 .. automodule:: reddit_decider
@@ -51,6 +53,17 @@ Setup :code:`reddit-experiments` in your application's configuration file:
 
 Integrate :code:`reddit-experiments` into Baseplate service
 -----------------------------------------------------------
+
+Upgrade or integrate reddit-experiments package:
+
+.. code-block:: python
+
+    # import latest reddit-experiments package in service requirements.txt
+    reddit-experiments>=1.3.7
+
+Initialize :code:`decider` instance on Baseplate context
+--------------------------------------------------------
+
 In your service's initialization process, add a :code:`decider` instance to baseplate's context:
 (Note the use of the :code:`ExperimentLogger`, which is used to publish exposure V2 events,
 an example can be seen `here <https://github.snooguts.net/reddit/reddit-service-graphql/blob/3734b51732c29d07eef32aced86677cce5064dbb/graphql-py/graphql_api/events/utils.py#L205>`_)
@@ -68,7 +81,7 @@ an example can be seen `here <https://github.snooguts.net/reddit/reddit-service-
     def make_wsgi_app(app_config):
         baseplate = Baseplate(app_config)
         decider_factory = decider_client_from_config(app_config=app_config,
-                                                     event_logger=ExperimentLogger,
+                                                     event_logger=ExperimentLogger(),
                                                      prefix="experiments.",
                                                      request_field_extractor=my_field_extractor)  # this is optional, can be `None` if edge_context contains all the fields you need
         baseplate.add_to_context("decider", decider_factory)
@@ -143,7 +156,7 @@ Configuration Class
 
 .. autoclass:: DeciderClient
 
-Configuration function
+Configuration Function
 ----------------------
 
 .. autofunction:: decider_client_from_config
@@ -153,3 +166,10 @@ Configuration Context Factory
 -----------------------------
 
 .. autoclass:: DeciderContextFactory
+
+Legacy API docs:
+----------------
+
+.. toctree::
+
+  legacy/index

docs/legacy/index.rst

@@ -0,0 +1,91 @@
+``reddit_experiments (legacy)``
+===============================
+
+.. automodule:: reddit_experiments
+
+Please consider upgrading your service to use the latest :ref:`reddit_decider` SDK
+to gain access to new features, such as **Mutually Exclusive Groups**, **Holdout Groups**, and **Dynamic Configurations**.
+
+
+Initialize :py:class:`~reddit_experiments.Experiments` instance on Baseplate context
+------------------------------------------------------------------------------------
+
+Add the :code:`Experiments` client to your application via::
+
+   baseplate.configure_context(
+      {
+         ...
+         "experiments": ExperimentsClient(event_logger),
+         ...
+      }
+   )
+
+or alternatively using::
+
+    experiments_factory = experiments_client_from_config(
+                              app_config=app_config,
+                              event_logger=ExperimentLogger
+    )
+    baseplate.add_to_context("experiments", experiments_factory)
+
+
+Configure :py:class:`~reddit_experiments.Experiments` client
+------------------------------------------------------------
+
+Configure the client in your application's configuration file:
+
+.. code-block:: ini
+
+   [app:main]
+
+   ...
+
+   # optional: a path to the file where experiment configuration is written
+   # (default: /var/local/experiments.json)
+   experiments.path = /var/local/foo.json
+
+   # optional: how long to wait for the experiments file to exist before failing
+   # (default: do not wait. fail immediately if not available)
+   experiments.timeout = 60 seconds
+
+   # optional: the base amount of time for exponential backoff while waiting
+   # for the file to be available.
+   # (default: no backoff time between tries)
+   experiments.backoff = 1 second
+
+   ...
+
+
+Usage
+-----
+Use the attached :py:class:`~reddit_experiments.Experiments` object in
+request to get a variant::
+
+   def my_method(request):
+       if request.experiments.variant("foo") == "bar":
+           pass
+
+Experiments API
+---------------
+
+.. autoclass:: Experiments
+   :members:
+
+Configuration Class
+-------------------
+
+.. autoclass:: ExperimentsClient
+
+Configuration Function
+----------------------
+
+.. autofunction:: experiments_client_from_config
+
+Configuration Context Factory
+-----------------------------
+
+.. autoclass:: ExperimentsContextFactory
+
+Link to Latest SDK
+------------------
+See :ref:`reddit_decider`

reddit_decider/__init__.py

@@ -1197,7 +1197,7 @@ def decider_client_from_config(
     The keys used in your app's :code:`some_config.ini` file should be prefixed, e.g.
     ``experiments.path``, etc.
 
-    Supported :code:`.ini` keys:
+    Supported config keys:
 
         ``path`` (optional)
             The path to the experiment configuration file generated by the

reddit_experiments/__init__.py

@@ -348,20 +348,20 @@ def experiments_client_from_config(
 ) -> ExperimentsContextFactory:
     """Configure and return an :py:class:`ExperimentsContextFactory` object.
 
-    The keys useful to :py:func:`experiments_client_from_config` should be prefixed, e.g.
+    The keys used in your app's :code:`some_config.ini` file should be prefixed, e.g.
     ``experiments.path``, etc.
 
-    Supported keys:
-
-    ``path`` (optional)
-        The path to the experiment configuration file generated by the
-        experiment configuration fetcher daemon.
-    ``timeout`` (optional)
-        The time that we should wait for the file specified by ``path`` to
-        exist.  Defaults to `None` which is `infinite`.
-    ``backoff`` (optional)
-        The base amount of time for exponential backoff when trying to find the
-        experiments config file. Defaults to no backoff between tries.
+    Supported config keys:
+
+        ``path`` (optional)
+            The path to the experiment configuration file generated by the
+            experiment configuration fetcher daemon.
+        ``timeout`` (optional)
+            The time that we should wait for the file specified by ``path`` to
+            exist.  Defaults to `None` which is `infinite`.
+        ``backoff`` (optional)
+            The base amount of time for exponential backoff when trying to find the
+            experiments config file. Defaults to no backoff between tries.
 
     :param raw_config: The application configuration which should have
         settings for the experiments client.