From 3264e20824fd15295a9dc39bba6a824d5dc6da7d Mon Sep 17 00:00:00 2001 From: Morgan Grant Date: Thu, 13 Jun 2019 12:53:19 -0700 Subject: [PATCH] update getting started page again --- docs/source/getting_started.rst | 235 +++++++++++++++----------------- 1 file changed, 110 insertions(+), 125 deletions(-) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 8cadb8f..0c31a1d 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -6,165 +6,150 @@ Getting Started Gotchas ---------------------------- -otree-redwood currently only works with python3 and Google Chrome. We have long term plans to add support for other browsers, but for now only google chrome will work correctly. +- otree-redwood currently only works with python3 and Google Chrome. We have long term plans to add support for other browsers, but for now only google chrome will work correctly -If you see an error that looks like `error: Python.h: No such file or directory`, you need to install the Python development libraries. These should be included on OS X. On Linux, you can install them with your package manager, for example: +- Redwood has not been tested on Windows. There's no reason it shouldn't work, but you may have some troubles, particularly with the virtual environment -.. code-block:: bash + - Consider using the Windows Subsystem for Linux. This will give you an Ubuntu-like environment on Windows and may make installation easier. You can find instructions for that on the Microsoft website `here `_ - sudo apt-get install python3-dev +- If you see an error that looks like `error: Python.h: No such file or directory`, you need to install the Python development libraries. These should be included on OS X. On Linux, you can install them with your package manager, for example: -If your Redwood experiment generates a large number of messages, you may get warnings from oTree about sqlite running out of connections. -The solution to this problem is to use a fully featured database such as Postgres. Instructions for integrating Postgres with -oTree can be found in the `oTree docs `_. + .. code-block:: bash -Option 1 - Clone the Leeps-Lab oTree repository. ------------------------------------------------- + sudo apt-get install python3-dev -.. code-block:: bash +- If your Redwood experiment generates a large number of messages, you may get warnings from oTree about sqlite running out of connections. The solution to this problem is to use a fully featured database such as Postgres. Instructions for integrating Postgres with oTree can be found in the `oTree docs `_ - git clone https://github.com/Leeps-Lab/oTree - cd oTree - git submodule update --recursive --remote - python3 -m venv venv - source venv/bin/activate - pip install -r requirements.txt - otree resetdb - otree runserver - -Cloning the repository is the fastest way to get started. You can copy one of -the 3 existing experiments or modify them in-place. - -Option 2 - Install otree-redwood from scratch +Installing otree-redwood -------------------------------------------------------------------- -1. Create and activate a python virtual environment to manage otree's python dependencies: +1. (Optional) Create and activate a python virtual environment to manage otree's python dependencies: -.. code-block:: bash + .. code-block:: bash - python3 -m venv venv - source venv/bin/activate + python3 -m venv venv + source venv/bin/activate -Virtual environments allow you to isolate your project's dependencies from your main python installation. Read more about virtual environments `here `_. + Virtual environments allow you to isolate your project's dependencies from your main python installation. Read more about virtual environments `here `_ 2. Use pip to install the otree-redwood library and the LEEPS fork of otree-core: -.. code-block:: bash + .. code-block:: bash - pip install otree-redwood git+https://github.com/leeps-lab/otree-core + pip install otree-redwood git+https://github.com/leeps-lab/otree-core 3. Start a new oTree project: -.. code-block:: bash + .. code-block:: bash - otree startproject oTree - cd oTree + otree startproject oTree + cd oTree 4. Save current versions of all dependencies in a requirements file so they can be quickly installed later: -.. code-block:: bash + .. code-block:: bash - pip freeze > requirements_base.txt + pip freeze > requirements_base.txt -Install dependencies later with + You can reinstall these dependencies later with -.. code-block:: bash + .. code-block:: bash - pip install -r requirements_base.txt + pip install -r requirements_base.txt 5. Update INSTALLED_APPS and EXTENSION_APPS in your settings.py -.. code-block:: python + .. code-block:: python - ... - INSTALLED_APPS = ['otree', 'django_extensions'] - EXTENSION_APPS = ['otree_redwood'] - ... + ... + INSTALLED_APPS = ['otree', 'django_extensions'] + EXTENSION_APPS = ['otree_redwood'] + ... 6. Create a new oTree experiment: -.. code-block:: bash - - otree startapp my_experiment + .. code-block:: bash + + otree startapp my_experiment 7. Use the otree-redwood classes in your experiment's models.py file: -Instead of extending otree.api.BaseGroup, your Group class extends one of the -otree-redwood Groups - :ref:`BaseGroup` or :ref:`DecisionGroup`. -Your Group class needs a ``period_length`` function. This is similar to oTree's -``timeout_seconds`` variable. When the period timer expires players will be -automatically moved to the next page. - -You still extend otree.api.BasePlayer, but your Player class needs an -``initial_decision`` function. This is the decision the player starts with. -You can let the player choose their initial decision with a normal oTree page. - -.. code-block:: python - - from otree_redwood.models import Event, DecisionGroup - - class Group(DecisionGroup): - - def period_length(self): - return Constants.period_length - - class Player(BasePlayer): - - def initial_decision(self): - return 0.5 - -8. Use the otree-redwood web components in one of your experiments HTML templates. - -Make sure your template inherits from "otree_redwood/Page.html" instead of the usual -"global/Page.html". This is required for the otree-constants webcomponent to work correctly. - -An example minimal otree_redwood template: - -.. code-block:: html+django - - {% extends "otree_redwood/Page.html" %} - - {% block scripts %} - - - - - - {% endblock %} - - {% block content %} - - - - -

Other Decision:

- - - - {% endblock %} + Instead of extending otree.api.BaseGroup, your Group class extends one of the + otree-redwood Groups - :ref:`BaseGroup` or :ref:`DecisionGroup`. + Your Group class needs a ``period_length`` function. This is similar to oTree's + ``timeout_seconds`` variable. When the period timer expires players will be + automatically moved to the next page. + + You still extend otree.api.BasePlayer, but your Player class needs an + ``initial_decision`` function. This is the decision the player starts with. + You can let the player choose their initial decision with a normal oTree page. + + .. code-block:: python + + from otree_redwood.models import Event, DecisionGroup + + class Group(DecisionGroup): + + def period_length(self): + return Constants.period_length + + class Player(BasePlayer): + + def initial_decision(self): + return 0.5 + + 8. Use the otree-redwood web components in one of your experiments HTML templates. + + Make sure your template inherits from "otree_redwood/Page.html" instead of the usual + "global/Page.html". This is required for the otree-constants webcomponent to work correctly. + + An example minimal otree_redwood template: + + .. code-block:: html+django + + {% extends "otree_redwood/Page.html" %} + + {% block scripts %} + + + + + + {% endblock %} + + {% block content %} + + + + +

Other Decision:

+ + + + {% endblock %}