Moved docs from RTD to ecommerce repo

ECOM-7190

docs/additional_features/change_processors.rst

+.. _Changing Payment Processors:
+
+#############################
+Changing Payment Processors
+#############################
+
+
+Payment processors sometimes experience temporary outages. When these outages
+occur, you can use Waffle switches to disable the faulty payment processor or
+processors, then re-enable them after the outage is over.
+
+The names of these switches use prefixes that are the value of the
+``PAYMENT_PROCESSOR_SWITCH_PREFIX`` setting. By default, this value is
+``payment_processor_active_``. The following table lists valid switches and the
+payment processors they control.
+
+.. list-table::
+   :widths: 15 45 10
+   :header-rows: 1
+
+   * - Payment Processor
+     - Switch Name
+     - Default Value
+   * - PayPal
+     - payment_processor_active_paypal
+     - True
+   * - CyberSource
+     - payment_processor_active_cybersource
+     - True
+
+In the unlikely event that all payment processors are disabled, the LMS will
+display an informative error message explaining why payment is not currently
+possible.

docs/additional_features/gate_ecommerce.rst

+.. _Gating ECommerce Features:
+
+####################################
+Gating E-Commerce Service Features
+####################################
+
+You can release new E-Commerce service features and functionality behind a
+feature gate. This project uses the `Waffle <http://waffle.readthedocs.org/en/latest>`_ library for feature gating.
+
+****************************
+Types of Feature Gates
+****************************
+
+Waffle supports the following types of feature gates.
+
+* Flag: This gate allows you to enable a feature for specific users, groups,
+  users who meet certain criteria (such as authenticated users or staff), or a
+  certain percentage of visitors.
+
+* Switch: This gate is a Boolean that turns a feature on or off for all
+  users.
+
+* Sample: This gate allows you to define the probability with which a given
+  feature will be on.
+
+For more information about creating or updating features and feature gates, see
+the `Waffle documentation <http://waffle.readthedocs.org/en/latest>`_.
+
+***************
+Feature Gates
+***************
+
+Waffle offers the following feature gates.
+
+.. list-table::
+   :widths: 35 10 60
+   :header-rows: 1
+
+   * - Name
+     - Type
+     - Purpose
+   * - user_enrollments_on_dashboard
+     - Switch
+     - Display a user's current enrollments on the dashboard user detail page.
+   * - publish_course_modes_to_lms
+     - Switch
+     - Publish prices and SKUs to the LMS after every course modification.
+   * - async_order_fulfillment
+     - Sample
+     - Specify what percentage of orders are fulfilled asynchronously.
+   * - ENABLE_CREDIT_APP
+     - Switch
+     - Enable the credit checkout page, from which learners can purchase credit
+       in a course.
+   * - ENABLE_NOTIFICATIONS
+     - Switch
+     - Enable email notifications for a variety of user actions, such as when
+       an order is placed.
+   * - PAYPAL_RETRY_ATTEMPTS
+     - Switch
+     - Enable users to retry unsuccessful PayPal payments.
+
+**********************************
+Enable a Feature Permanently
+**********************************
+
+If you want to make a feature permanent, remove its feature gate from relevant
+code and tests, and delete the gate from the database.

docs/additional_features/index.rst

+.. _Additional Ecommerce Features:
+
+################################
+Additional E-Commerce Features
+################################
+
+After you install the basic features of the E-Commerce service on your instance
+of the Open edX platform, you can enable or install additional features. You
+can set up E-Commerce to send email, switch payment processors, or track event
+data if one of your usual processors is unavailable.
+
+.. toctree::
+   :maxdepth: 2
+
+   send_notifications
+   change_processors
+   track_data
+   gate_ecommerce
+   maintain_ecommerce
+
+
+
+.. Moved globalization.rst to desktop/Works In Progress folder, pending
+.. possible move to ICRV.
+

docs/additional_features/maintain_ecommerce.rst

+.. _Maintaining ECommerce:
+
+####################################
+Maintaining the E-Commerce Service
+####################################
+
+Most of the time, you do not have to perform maintenance on the E-Commerce
+service. However, E-Commerce creates **basket** objects to track products that
+users want to purchase before users place an order. As more baskets and orders
+are created, the baskets table can grow large. Depending on your database
+backend, a large table can become difficult to manage and migrate. After an
+order is placed, you can delete the corresponding basket from the baskets
+table.
+
+To delete one or more baskets, follow these steps.
+
+.. note::
+ Baskets that contain products but that are not used to create orders, such as
+ when a user adds a product to a basket but does not complete the order
+ process, are not deleted. These baskets provide records that users intended to
+ purchase a product.
+
+#. To display the number of baskets that you can delete, run the following
+   command.
+
+   .. code-block:: bash
+
+     $ ./manage.py delete_ordered_baskets
+
+#. To delete all the baskets that appear after you run the command in step 1,
+   use the --commit option.
+
+   .. code-block:: bash
+
+     $ ./manage.py delete_ordered_baskets --commit

docs/additional_features/send_notifications.rst

+.. _Sending Notifications:
+
+#######################
+Sending Notifications
+#######################
+
+The edX E-Commerce service uses the `Communications API <http://django-oscar.readthedocs.org/en/latest/howto/how_to_customise_oscar_communications.html#communications-api>`_ 
+that is part of `Oscar <https://github.com/django-oscar/django-oscar>`_ to create and send notifications in the form of email messages. To
+send notifications, you must set up notifications, create one or more email
+messages, and then send the email messages.
+
+*************************
+Set Up Notifications
+*************************
+
+#. Enable the E-Commerce service to send notifications. To do this, change the
+   value of the ``ENABLE_NOTIFICATIONS`` feature flag to True.
+#. Define communication type codes to refer to particular types of
+   notification. For example, you might define a communication type code named
+   ``COURSE_SEAT_PURCHASED`` to correspond to the purchase of a course seat.
+
+*************************
+Create an Email Message
+*************************
+
+The E-Commerce service can send both HTML and plain text email messages. To
+create an email message, create the following three files in the
+``ecommerce/ecommerce/templates/customer/emails/`` folder.
+
+   * An HTML template that extends ``email_base.html`` and includes the body of
+     the email.
+   * A plain text file that contains the email's subject line.
+   * A plain text file that contains the body of the email.
+
+Use the following convention to name these files.
+
+``commtype_{communication type code}_body.html``
+
+For example, if the communication type code is ``course_seat_purchased``, the
+three files would have the following names.
+
+* ``commtype_course_seat_purchased_body.html``
+* ``commtype_course_seat_purchased_body.txt``
+* ``commtype_course_seat_purchased_subject.txt``
+
+.. note::
+ To add a custom email body, override ``block body`` in the email_base.html
+ file. To add a custom footer, override ``block footer`` in the email_base.html
+ file.
+
+*******************
+Send Email Messages
+*******************
+
+To send email messages, use the ``send_notification(user, commtype_code,
+context)`` method. This method is implemented in
+``ecommerce/ecommerce/notifications/notifications.py``.
+

docs/additional_features/track_data.rst

+.. _Tracking Data:
+
+###################
+Tracking Data
+###################
+
+The E-Commerce service uses `Segment <https://segment.com/>`_ to collect business intelligence data.
+
+To emit events to your Segment project, specify your Segment project's API key
+as the value of the ``SEGMENT_KEY`` setting.

docs/create_products/create_course_seats.rst

+.. _Create Course Seats:
+
+####################
+Create Course Seats
+####################
+
+A course seat represents an enrollment track, sometimes called an enrollment
+mode. For information about the enrollment tracks that edX offers, see
+:ref:`enrollment track<enrollment_track_g>`.
+
+You create course seats by creating a course on the **Create New Course** page
+in the course administration tool, which is located at
+``http://localhost:8002/courses/``. After you create a course, the E-Commerce
+service creates the course seats that are associated with that course.
+
+To create a course seat, follow these steps.
+
+#. Follow the steps in :ref:`Create Products Overview` to start your E-Commerce
+   server.
+#. In a browser on your E-Commerce server, go to
+   ``http://localhost:8002/courses`` to access the **Courses** page.
+#. On the **Courses** page, select **Add New Course**.
+#. On the **Add New Course** page, enter the information for your course in the
+   following fields.
+
+   * **Course ID**
+   * **Course Name**
+
+#. For **Course Type**, select a course type and the options for that course
+   type.
+
+   * If you select **Free (Audit)**, you must specify whether you want to allow
+     honor code learners to earn an honor code certificate. To do this, select
+     **Yes** under **Include Honor Seat**.
+
+   * If you select **Verified**, you must add the following information.
+
+     * **Price (in USD)**
+     * **Upgrade Deadline**
+     * **Verification Deadline**
+     * **Include Honor Seat**: This option grants honor code certificates to
+       learners who successfully complete the course.
+
+   * If you select **Professional Education**, you must add the following
+     information.
+
+     * **Price (in USD)**
+     * **ID Verification Required?**
+     * **Upgrade Deadline**
+
+   * If you select **Credit**, you must add the following information.
+
+     * **Price (in USD)**: The price for a verified certificate.
+     * **Upgrade Deadline**
+     * **Credit Provider**
+     * **Price (USD)**: The price for course credit.
+     * **Credit Hours**
+     * **Upgrade Deadline**
+     * **Verification Deadline**
+     * **Include Honor Seat**: This option grants honor code certificates to
+       learners who successfully complete the course.
+
+#. Select **Create Course**.
+
+.. include:: ../links/links.rst

docs/create_products/create_enrollment_codes.rst

+.. _Enable and Create Enrollment Codes:
+
+#####################################
+Enable and Create Enrollment Codes
+#####################################
+
+.. note::
+  The enrollment codes in this topic are not related to the enrollment codes in
+  the :ref:`Create and Manage Coupons` topic.
+
+Enrollment codes allow users to purchase bulk enrollments for a course.
+
+************************
+Enable Enrollment Codes
+************************
+
+You must enable enrollment codes in the E-Commerce service and in individual
+courses.
+
+#. To enable enrollment codes in the E-Commerce service, run the site
+   configuration command together with the following option.
+
+   ::
+
+     ``--enable-enrollment-codes=True``
+
+   For more information, see :ref:`Add Another Site Partner and Site
+   Configuration`.
+
+#. To enable enrollment codes in individual courses, follow these steps.
+
+   #. Follow step 1 through step 5 in :ref:`Create Course Seats` to access and
+      select options on the **Add New Course** page. Do not select **Create
+      Course** after you complete step 5.
+   #. Select **Include Enrollment Code**.
+   #. Select **Create Course**.
+
+After you select **Create Course**, enrollment codes are enabled for that
+course.
+
+************************
+Create Enrollment Codes
+************************
+
+#. Go to the enrollment page for the course.
+#. On the enrollment page, select **Buy enrollment**. Do not select **Enroll in
+   the course**.
+
+   The basket page opens.
+
+#. For **Number of Enrollment Codes**, enter the number of enrollment codes
+   that you want. Each enrollment code is for one course seat.
+#. Select **Purchase**.
+
+After you select **Purchase**, you receive an e-mail message that contains a
+link to a .csv file. The .csv file lists the enrollment codes.
+
+
+
+.. include:: ../links/links.rst

docs/create_products/create_products_overview.rst

+.. _Create Products Overview:
+
+###########################
+Creating Products Overview
+###########################
+
+The edX platform offers several types of products. You create these products in
+E-Commerce web pages.
+
+* Course seats represent an enrollment track. Each course seat has an
+  associated set of attributes, such as price and certificate availability. The
+  edX code uses course seats to determine how a given enrollment should be
+  handled. For more information, see :ref:`enrollment
+  track<enrollment_track_g>` or :ref:`Create Course Seats`.
+
+* Coupons allow users to offer learners a discount, either percentage or fixed
+  amount, off a course enrollment. For more information, see :ref:`Create and
+  Manage Coupons`.
+
+* Enrollment codes allow users to purchase bulk enrollments for a course.
+
+******************************
+Prepare to Create a Product
+******************************
+
+Before you create a product, complete the following steps to start the
+E-Commerce service on your site.
+
+#. In the ecommerce and LMS configuration files (``/edx/etc/ecommerce.yml`` and
+   ``/edx/app/edxapp/lms.auth.json``, respectively), verify the following
+   settings.
+
+   .. note::
+    If you are using `devstack`_, these values are set correctly for you.
+    However, edX recommends that you verify these values.
+
+   * The ``EDX_API_KEY`` value in the LMS file must be the same as the
+     ``EDX_API_KEY`` value in the ecommerce file. If the values differ, change
+     the value in the LMS file to match the ecommerce file.
+   * The ``ECOMMERCE_API_SIGNING_KEY`` value in the LMS file must be the same
+     as the ``JWT_SECRET_KEY`` value in the ecommerce file. If the values
+     differ, change the value in the LMS file to match the ecommerce file.
+
+#. On devstack, start the E-Commerce server on port 8002, and start the LMS
+   on port 8000.
+
+
+.. include:: ../links/links.rst

docs/create_products/index.rst

+.. _Create Ecommerce Products:
+
+############################
+Create E-Commerce Products
+############################
+
+After you :ref:`configure a partner and at least one site <Configure a Site
+Partner and Site Configuration>` for the E-Commerce service to use, and you
+have compiled and moved your static assests, you can create products. For more
+information, see the following topics.
+
+.. toctree::
+   :maxdepth: 2
+
+   create_products_overview
+   create_course_seats
+   create_coupons
+   create_enrollment_codes
+
+.. include:: ../links/links.rst

docs/index.rst

-.. ecommerce documentation master file, created by
-   sphinx-quickstart on Sun Feb 17 11:46:20 2013.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+.. _Adding ECommerce to Open edX:
 
-edX E-Commerce Service
-======================
+##########################################
+Adding E-Commerce to the Open edX Platform
+##########################################
 
-These docs have moved to the `Open edX Installing, Configuring, and Running (ICR) guide <http://edx.readthedocs.org/projects/edx-installing-configuring-and-running/en/latest/ecommerce/index.html>`_. To contribute, please open a PR against https://github.com/edx/edx-documentation.
+EdX uses a Django application called ``ecommerce`` to provide the platform with
+ecommerce functionality. This `E-Commerce service`_ extends `Oscar`_, an open
+source Django ecommerce framework, to manage the edX product catalog and handle
+orders for those products. The following sections describe how to install and
+use the E-Commerce service with the Open edX platform.
+
+.. toctree::
+   :maxdepth: 2
+
+   install_ecommerce
+   manage_assets
+   create_products/index
+   manage_orders
+   test_features
+   test_ecommerce
+   additional_features/index
+
+To complete the procedures that this section describes, you use both the Django
+administration site and the Course Administration Tool (CAT). The CAT is a web
+app that is included with the E-Commerce service. The CAT enables you to
+configure and manage products that are associated with the courses on your
+instance of the Open edX learning management system (LMS).
+
+In addition to these required steps, you can add optional features to the
+E-Commerce service for your instance of the Open edX platform. For more
+information, see :ref:`Additional Ecommerce Features`.
+
+
+.. include:: links/links.rst
+
+.. TODO
+..   - Oscar Dashboard
+..   - Payment processors
+..   - API
+..   - Course Administration Tool

docs/manage_assets.rst

+.. _Manage Static Assets:
+
+##############################
+Manage Static Assets
+##############################
+
+After you :ref:`configure a partner and at least one site <Configure a Site
+Partner and Site Configuration>` for the E-Commerce system to use, you must
+compile all static assets and move them to the correct location to be served.
+The edX E-Commerce service uses `django-compressor`_ and `RequireJS`_ to manage
+static assets.
+
+* django-compressor compiles and minifies CSS and JavaScript files,
+  and names files to facilitate cache busting after new file deployment.
+
+* RequireJS manages JavaScript dependencies.
+
+.. note::
+
+  The static file directories are set up so that ``make static`` reads the
+  build output directory of ``r.js`` before it checks for assets in the
+  ``ecommerce/static/`` directory. EdX does not recommend that you run ``make
+  static`` locally. If you run ``make static`` or ``r.js`` locally, make sure
+  you delete the ``ecommerce/static/build`` folder or that you run ``make
+  static`` before you continue with development. If you do not run ``make
+  static`` again, django-compressor ignores all changes that you make to
+  static files.
+
+**********************************
+Compile and Move Static Assets
+**********************************
+
+To compile and move your static assets and deploy your E-Commerce service,
+execute the following command locally or on another server.
+
+.. code-block:: bash
+
+  $ make static
+
+If you create new pages that have RequireJS dependencies, remember to add your
+new JavaScript modules to the RequireJS build file for the project. This is the
+``build.js`` file.
+
+.. include:: links/links.rst

docs/manage_orders.rst

+.. _Manage Orders:
+
+##################
+Manage Orders
+##################
+
+EdX has created a framework that manages order placement and fulfillment for
+digital products. Most of the products that edX supports involve modifications
+to enrollments.
+
+The edX framework allows modules that fulfill enrollment-related products to
+interact with the `edX Enrollment API`_, which is a part of the LMS. This
+process can be either synchronous or asynchronous.
+
+
+******************
+Place an Order
+******************
+
+To place an order, you need the following information.
+
+* Order number
+* User
+* Basket
+* Shipping method
+* Shipping charge
+* Billing address
+* Order total
+
+To place an order, use the ``handle_order_placement()`` method that
+``EdxOrderPlacementMixin`` provides. If you modify this code, make sure that
+the code collects payment before it creates order objects.
+
+******************
+Fulfill Orders
+******************
+
+To fulfill orders, emit a ``post_checkout`` signal. An internal fulfillment API
+then delegates fulfillment of individual order items to the appropriate
+fulfillment modules.
+
+***************************
+About Fulfillment Modules
+***************************
+
+The E-Commerce base fulfillment module has the following interface.
+
+.. code-block:: bash
+
+    fulfill_product(product)
+
+    revoke_line(line)
+
+Every ``ProductType`` has a corresponding module that extends this interface
+and fulfills order items of that particular ``ProductType``. To fulfill an
+order, the system gives each fulfillment module configured in settings
+(``_oscar.py``) an opportunity to fulfill order lines.
+
+* The ``fulfill_product`` method fulfills the order. For example,
+  ``fulfill_product`` might enroll a learner in a course or upgrade the learner
+  to a verified certificate).
+
+* The ``revoke_line`` method revokes a specific order line. For example,
+  ``revoke_line`` might unenroll learners from courses or downgrade a learner
+  from a verified seat.
+
+
+
+*************************************
+Recover from a Fulfillment Error
+*************************************
+
+If a fulfillment operation fails, the E-Commerce service assigns the order a
+status indicating the reason for the failure. If you have enabled asynchronous
+order fulfillment, the service tries again to fulfill the order. You can also
+manually retry fulfillment of a failed order from the `Oscar`_ order dashboard.
+
+.. include:: links/links.rst
+

docs/test_features.rst

+.. _Test Features:
+
+###############
+Test Features
+###############
+
+.. This topic will move to a different section in the ICR guide after the reorg
+.. of the guide is complete.
+
+When you create a new feature for the Open edX platform, you must write two
+kinds of tests for that feature: general tests that evaluate the feature on the
+Open edX platform, and tests that are specific to the type of feature that you
+create. For example, if you create a coupon codes feature for use with the edX
+Ecommerce service, you must write both Open edX tests and Ecommerce tests. This
+section describes the general tests that you must write for the Open edX
+platform.
+
+***********************************
+Tests for the Open edX Platform
+***********************************
+
+You must write the following types of tests for all new features that you
+create for the Open edX platform.
+
+* Django tests. To learn how to test Django code, see the `Testing in Django`_
+  documentation provided by the Django Software Foundation.
+
+* Acceptance tests. These tests verify behavior that relies on external
+  systems, such as the LMS or payment processors. At a minimum, you must run
+  these tests against a staging environment before you deploy code to
+  production to verify that critical user workflows are functioning as
+  expected. With the right configuration, you can also run the tests locally.
+
+
+.. include:: links/links.rst