docs: update the readmes and the how-tos, and add quickstart and a tu…

…torial (#61)

* docs: update the readmes and the how-tos, add quickstart and a tutorial

* docs: improve the doc with feedback

* docs: ordered lists in READMEs

README.md

@@ -1,6 +1,27 @@
-# ⭐ Open edX WooCommerce Plugin
+# ⭐ Open edX Commerce (WordPress Plugin)
 
-It is a free, open-source WordPress plugin that aims to integrate third-party e-commerce, WooCommerce, with your Open edX platform.
+The "Open edX Commerce" package is a free and open-source WordPress plugin that allows you to integrate WooCommerce with your Open edX platform.
+
+**What does this mean?**
+You can create Open edX courses as products in WooCommerce, and when you perform purchase or refund operations for these products, your Open edX platform will reflect these changes.
+
+Here are some things you can do with this plugin:
+
+- **Create Open edX courses as products:** When you create products using WooCommerce, you can designate them as Open edX courses. If you do, you can assign the course mode and course_id you registered in your Open edX platform.
+
+- **Add settings for the connection with Open edX:** You'll have a new option in your WordPress settings to store authentication-related information for your Open edX platform.
+
+- **Enrollment Manager:** You'll have a table that records all enrollment requests made through purchasing products that are Open edX courses.
+
+- **View the enrollment requests from the orders:** When a person purchases WordPress, a WooCommerce order is generated. If an order includes a product that is an Open edX course, you can easily access the related enrollment request created with this plugin.
+
+- **Create enrollments in Open edX:** When an order containing an Open edX course is processed, it automatically creates an enrollment request.
+    - You can also include the option to apply the "force" flag, disregarding the course's enrollment end dates.
+    - Starting from version Quince of Open edX, you can use the option to create enrollment allowed for non-registered users on the platform.
+
+- **Create soft unenrollments from refunds:** The enrollment record is maintained, but the "is_active" attribute of the enrollment is false. Deleting an "enrollment allowed" is also supported, but only from version Quince.
+
+- **Obtain enrollment information:** This requests the Open edX APIs to retrieve the enrollment status of a user in a course.
 
 # Installation
 
@@ -12,11 +33,15 @@ It is a free, open-source WordPress plugin that aims to integrate third-party e-
 
 ## Manual installation
 
-- Download the ZIP version in our [GitHub repository](https://github.com/eduNEXT/openedx-woocommerce-plugin/releases).
+1. Download the ZIP version on [the release page in the GitHub repository](https://github.com/openedx/openedx-wordpress-ecommerce/releases).
 
-<img src="https://i.ibb.co/YTSLYf4/zip-from-release.png" alt="Download ZIP from release">
+<img src="docs/source/_images/zip-from-release.png" alt="Download ZIP from release">
 
-- Log in to your WordPress dashboard, navigate to the Plugins menu, click "Add New," and upload the ZIP version of this project.
+2. Log in to your WordPress admin dashboard, navigate to the Plugins menu in the sidebar and click **Add New**.
+
+3. Upload the ZIP version of this project.
+
+4. Activate the plugin.
 
 <!---
 In the search field, type "Open edX WooCommerce Plugin," then click "Search Plugins." Once you've found us, you can view its details and install it by clicking "Install Now," WordPress will take it from there.
@@ -25,11 +50,9 @@ In the search field, type "Open edX WooCommerce Plugin," then click "Search Plug
 
 # Getting Started
 
-Connect your WordPress site with your Open edX platform by following these steps:
-- Install the Open edX WooCommerce Plugin.
-- Configure the plugin.
-- Create a product with the course info.
-- You can start selling Open edX courses with WooCommerce!
+Let's start installing and configuring the Open edx Commerce plugin to connect your WordPress site with the enrollment APIs from your Open edX platform.
+
+[Link to the Quickstart in the documentation.](https://github.com/openedx/openedx-wordpress-ecommerce/blob/main/docs/source/plugin_quickstart.rst)
 
 
 # Open edX Compatibility
@@ -40,7 +63,7 @@ Connect your WordPress site with your Open edX platform by following these steps
 
 # Getting Help
 
-To report a bug or request a feature, visit [issues](https://github.com/eduNEXT/openedx-woocommerce-plugin/issues).
+To report a bug or request a feature, visit [issues](https://github.com/openedx/openedx-wordpress-ecommerce/issues).
 
 
 ## Documentation

README.txt

@@ -34,10 +34,11 @@ Here are some things you can do with this plugin:
 - **Create soft unenrollments from refunds:** The enrollment record is maintained, but the "is_active" attribute of the enrollment is false. Deleting an "enrollment allowed" is also supported, but only from version Quince.
 Obtain enrollment information: This requests the Open edX APIs to retrieve the enrollment status of a user in a course.
 
+- **Obtain enrollment information:** This requests the Open edX APIs to retrieve the enrollment status of a user in a course.
 
 Below are some links to help you get started with Open edX WooCommerce Plugin:
 
-- <a href="https://edunext-docs-openedx-woocommerce-plugin.readthedocs-hosted.com/en/latest/quickstart.html" target="_blank">Quick Start Guide</a>
+- <a href="https://edunext-docs-openedx-woocommerce-plugin.readthedocs-hosted.com/en/latest/plugin_quickstart.html" target="_blank">Quick Start Guide</a>
 - <a href="https://edunext-docs-openedx-woocommerce-plugin.readthedocs-hosted.com/en/latest/how-tos/index.html" target="_blank">How-to Guides</a>
 
 == Installation ==
@@ -50,11 +51,21 @@ Below are some links to help you get started with Open edX WooCommerce Plugin:
 
 = Manual installation =
 
-- Download the ZIP version in our [GitHub repository](https://github.com/eduNEXT/openedx-wordpress-ecommerce/releases).
+1. Download the ZIP version on [the release page in the GitHub repository](https://github.com/openedx/openedx-wordpress-ecommerce/releases).
 
-<img src="https://i.ibb.co/YTSLYf4/zip-from-release.png" alt="Download ZIP from release">
+<img src="docs/source/_images/zip-from-release.png" alt="Download ZIP from release">
 
-- Log in to your WordPress dashboard, navigate to the Plugins menu, click "Add New," and upload the ZIP version of this project.
+2. Log in to your WordPress admin dashboard, navigate to the Plugins menu in the sidebar and click **Add New**.
+
+3. Upload the ZIP version of this project.
+
+4. Activate the plugin.
+
+== Quickstart ==
+
+Let's start installing and configuring the Open edx Commerce plugin to connect your WordPress site with the enrollment APIs from your Open edX platform.
+
+[Link to the Quickstart in the documentation.](https://github.com/openedx/openedx-wordpress-ecommerce/blob/main/docs/source/plugin_quickstart.rst)
 
 == Frequently Asked Questions ==
 
@@ -72,8 +83,6 @@ Contributions are very welcome. Please read [How To Contribute](https://openedx.
 
 This project accepts all contributions, bug fixes, security fixes, maintenance work, or new features. However, please discuss your new feature idea with the maintainers before beginning development to maximize the chances of accepting your change. You can start a conversation by creating a new issue on this repo summarizing your idea.
 
-
-
 == Changelog ==
 
 You can find the [Changelog in the GitHub repository.](https://github.com/eduNEXT/openedx-wordpress-ecommerce/blob/main/CHANGELOG.md)

docs/source/conf.py

@@ -64,7 +64,7 @@
 
 html_theme_options = {
 
-    "repository_url": "https://github.com/eduNEXT/openedx-woocommerce-plugin",
+    "repository_url": "https://github.com/openedx/openedx-wordpress-ecommerce",
     "repository_branch": "main",
     "path_to_docs": "docs/source",
     "use_repository_button": True,

docs/source/decisions/index.rst

@@ -8,3 +8,4 @@ Decisions
    0001-purpose-of-this-repo
    0002-api-connection
    0003-fulfillment-and-refund
+   0004-naming-of-the-plugin

docs/source/how-tos/create_an_openedx_app.rst

@@ -1,30 +1,44 @@
 Create an Open edX Application for the Plugin Settings
 =======================================================
 
-You will learn how to create an Open edX Application for filling out the form in the Open edX Sync Plugin Settings in our Wordpress Settings.
+You will learn how to create an Open edX Application for filling out the form in the Open edX Sync Plugin Settings in our WordPress Settings.
+
+Index
+-------
+- `Requisites`_
+- `Create an Open edX Application to Configure the Open edX Commerce plugin`_
+- `Next Steps`_
+
+Requisites
+-----------
+
+Have access to a Django admin dashboard for your Open edX platform.
+
+Create an Open edX Application to Configure the Open edX Commerce plugin
+-------------------------------------------------------------------------
 
 #. Go to Applications in your Django Admin in your Open edX instance. (URL: `<domain>/admin/oauth2_provider/application/`)
 
     .. image:: /_images/how-tos/create_an_openedx_app/applications.png
         :alt: Applications in Django Admin
 
-#. Create an Application with a staff user and Client Credentials as Authorization grant type.
+#. Create an Application with a staff user and **Client Credentials** as **Authorization grant type**.
 
     .. note:: Why do we need a staff user? Because we use those credentials to create, edit, and delete enrollments, which are staff operations.
 
     .. image:: /_images/how-tos/create_an_openedx_app/add-application.png
         :alt: Add Application
 
-#. Use your platform domain and your application's client id and client secret in the Open edX Sync Plugin Settings in your WordPress Settings.
+#. Use your platform **domain** and your **application's client id and client secret** in the Open edX Sync Plugin Settings in your WordPress Settings.
 
     .. image:: /_images/how-tos/create_an_openedx_app/openedx-sync-plugin-settings.png
         :alt: Open edX Sync Plugin Settings
 
-#. Test the credentials by clicking "Save Changes" and "Generate JWT Token." 
+#. Test the credentials by clicking **Save Changes** and **Generate JWT Token**. 
 
-.. note:: If you don't have credentials to enter the Django Admin, you need to contact an operator of your Open edX instance to provide you the client id and client secret of an Application with Client Credentials as Authorization grant type and staff user.
+.. note:: If you do not have credentials to enter the Django Admin, you need to contact an operator of your Open edX instance to provide you the **client id and client secret of an Application** with **Client Credentials** as **Authorization grant type** and **staff user**.
 
 Next Steps
 -----------
 
-- :doc:`Create enrollment requests manually </how-tos/create_enrollment_requests_manually>`.
+- :doc:`How-to: Create enrollment requests manually </how-tos/create_enrollment_requests_manually>`.

docs/source/how-tos/create_enrollment_requests_manually.rst

@@ -1,42 +1,65 @@
-Create enrollment requests manually
+Create Enrollment Requests Manually
 ====================================
 
-The Open edX WooCommerce Plugin uses Enrollment Request to manage the enrollments generated by the WooCommerce integration, but you can create an Enrollment Request manually.
+The Open edX WooCommerce Plugin uses Enrollment Request to manage the enrollments generated by the WooCommerce integration, but you can create it manually.
 
 In this section, you will learn how to create an Enrollment Request manually.
 
+Index
+-------
+- `Requisites`_
+- `Create an Enrollment Request`_
+- `Exploring the Enrollment Request View`_
+- `Next Steps`_
+
 Requisites
 -----------
 
-To connect with the Open edX platform, you must have valid settings for this plugin. If you don't have this plugin set yet, the how-to :doc:`Create an Open edX Application for the Plugin Settings </how-tos/create_an_openedx_app>` will be helpful.
+To connect with the Open edX platform, you must have valid settings for this plugin. If you do not have this plugin set yet, the :doc:`How-to: Create an Open edX Application for the Plugin Settings </how-tos/create_an_openedx_app>` will be helpful.
 
-Steps
-------
+Create an Enrollment Request
+-----------------------------
 
 #. Enter the Enrollments Manager option in your WordPress dashboard's Open edX Sync tab.
 
     .. image:: /_images/how-tos/create_enroll_request/menu.png
         :alt: Enrollments Manager option
 
-#. Create a new Enrollment Request (URL: `<domain>/wp-admin/post-new.php?post_type=openedx_enrollment`)
+#. Click **Add New** and fill out the form with the following fields:
+
+- **Course ID**: the ID from your Open edX platform course. e.g. ``course-v1:edX+DemoX+Demo_Course``. 
+
+- **User Email**: the user's email address that will be used in the request.
+
+- **Course Mode**: the mode of your enrollment request. Make sure to set a mode that your course has. We only support the modes that come by default on the Open edX platform.
+
+- **Request type**: If you select **Enroll**, you will create an enrollment, and if you choose **Un-enroll**, you will set a soft un-enrollment (enrollment with status inactive) if you update in Open edX.
+
+- **WC Order ID (Auto-filled)**: You can leave this field blank. If your request was created automatically and has an order associated, this field will fill automatically.
 
     .. image:: /_images/how-tos/create_enroll_request/new_enroll_request.png
         :alt: New Enrollment Request
 
-* Use a valid course ID that will be used in the request. e.g. course-v1:edX+DemoX+Demo_Course.
 
-* Enter the email of the user who will be used in the request.
+Exploring the Enrollment Request View
+----------------------------------------
 
-* Select a Course Mode that the course has.
+Checkboxs
+^^^^^^^^^^
 
-* Select the type of request you want to execute. If you select **Enroll**, you will create an enrollment, and if you select **Un-enroll**, you will set a soft unenrollment (enrollment with status inactive).
+- **Use the "force" flag**: if you select this, the action will not consider the course enrollment end dates.
 
-* If this request has an Order associated, you can fill in the "WC Order ID" field.
+- **Creating a course enrollment allowed if the user does not exist**: if you select this, create a register in the table Course Enrollment Allowed if the email we use in the request is not a user in our Open edX platform yet. It is available only if you have a release greater or equal to Quince.
 
-* If you select to use the force flag, the action will not consider the course enrollment dates.
+Buttons
+^^^^^^^^
 
-* Creating a "course enrollment allowed" if the user doesn't exist is available only if you have a release greater than Palm.
+- **Save in WordPress**: this allows you to store the form information in WordPress.
+- **Save and update Open edX**: save the information in WordPress and create a POST API request, considering all the flags and fields except the **WC Order ID.**
+- **Read from Open edX**: bring information with GET methods over the API and only use the **Couse ID** and **User email** fields.
+- **View Order**: allows you to navigate from the Enrollment Request to the Order associated with that request.
 
-And that's it!
+Next Steps
+-----------
 
-You can save it in Wordpress or Save and Update it in Open edX.
+- :doc:`Tutorial: Configure your WordPress so that purchases and refunds automatically generate enrollments </tutorials/configuration_to_automate_enrolls>`.

docs/source/how-tos/create_openedx_course_wordpress.rst

@@ -0,0 +1,29 @@
+Create an Open edX Course in WordPress
+=======================================
+
+Index
+------
+- `Create an Open edX Course`_
+- `Next Steps`_
+
+Create an Open edX Course
+--------------------------
+
+#. In the sidebar of the WordPress admin dashboard, go to **Products** and then to **Add New**.
+
+#. Click the **Open edX Course checkbox** and fill in the information required.
+
+    .. image:: /_images/how-tos/create_openedx_course_product/add-base-info.png
+        :alt: Add new Open edX Course product.
+
+
+    .. warning:: We recommend not to use the **Downloadable check** when you use the **Open edX Course check** to avoid problems creating the enrollment. For more information, visit :doc:`Decisions: Fulfillment and Refund </decisions/0003-fulfillment-and-refund>`.
+
+#. Add more information in your product as a title, description and image.
+
+#. Save your changes.
+
+Next Steps
+-----------
+
+- :doc:`Tutorial: Configure your WordPress so that purchases and refunds automatically generate enrollments </tutorials/configuration_to_automate_enrolls>`.

docs/source/how-tos/index.rst

@@ -7,3 +7,5 @@ How-tos
 
    create_an_openedx_app
    create_enrollment_requests_manually
+   create_openedx_course_wordpress
+   refund_order_with_openedx_course

docs/source/how-tos/refund_order_with_openedx_course.rst

@@ -0,0 +1,35 @@
+Refund an Order With an Open edx Course from a WooCommerce Order
+==================================================================
+
+You will learn how to refund an Open edX product from a WooCommerce order.
+
+Index
+------
+- `Refund an Open edX Course`_
+- `Expected Behavior`_
+- `Next Steps`_
+
+Refund an Open edX Course
+--------------------------
+To refund products in order with WooCommerce, you can follow the `WooCommerce Refund Documentation <https://woo.com/document/woocommerce-refunds/>`_.
+
+For a refund to generate an un-enrollment in your Open edX platform, the following is required:
+
+#. The item you will refund must be an Open edX Course (:doc:`How-to: Create an Open edX Course in WordPress </how-tos/create_openedx_course_wordpress>`).
+
+#. You need to add a **Quantity** for that item.
+
+    .. image:: /_images/decisions/refund-order.png
+        :alt: Refund process marking the course to be refunded
+
+Expected Behavior
+------------------
+
+- When the refund is made, an Enrollment Request with the **Un-enroll** request type will automatically be created in your WordPress site.
+
+- Have a course enrollment with the course and user and the ``is_active`` flag in ``False`` in your Open edX platform.
+
+Next Steps
+-----------
+
+- :doc:`Decisions </decisions/index>`.

docs/source/index.rst

@@ -16,8 +16,10 @@ User Guide
     :titlesonly:
 
     plugin_quickstart
-    decisions/index
+    tutorials/index
     how-tos/index
+    decisions/index
+
 
 
 Open edX Compatibility
@@ -31,17 +33,17 @@ Open edX Compatibility
 Releases
 ---------
 
-The Releases are listed on the `Github release page <https://github.com/eduNEXT/openedx-woocommerce-plugin/releases>`_. And all notable changes to this project are documented in the `CHANGELOG <https://github.com/eduNEXT/openedx-woocommerce-plugin/blob/main/CHANGELOG.md>`_ file.
+The Releases are listed on the `Github release page <https://github.com/openedx/openedx-wordpress-ecommerce/releases>`_. And all notable changes to this project are documented in the `CHANGELOG <https://github.com/openedx/openedx-wordpress-ecommerce/blob/main/CHANGELOG.md>`_ file.
 
 Source code
 -----------
 
-The complete source code for Open edX WooCommerce Plugin is available on Github: https://github.com/eduNEXT/openedx-woocommerce-plugin
+The complete source code for Open edX WooCommerce Plugin is available on Github: https://github.com/openedx/openedx-wordpress-ecommerce
 
 Support
 --------
 
-To report a bug or request a feature, visit `issues <https://github.com/eduNEXT/openedx-woocommerce-plugin/issues>`_.
+To report a bug or request a feature, visit `issues <https://github.com/openedx/openedx-wordpress-ecommerce/issues>`_.
 
 Contributing
 -------------
@@ -53,7 +55,7 @@ This project accepts all contributions, bug fixes, security fixes, maintenance w
 License
 --------
 
-The code in this repository is licensed under version 2 of the GNU General Public License. Please see the `LICENSE <https://github.com/eduNEXT/openedx-woocommerce-plugin/blob/main/LICENSE.txt>`_ file for details.
+The code in this repository is licensed under version 2 of the GNU General Public License. Please see the `LICENSE <https://github.com/openedx/openedx-wordpress-ecommerce/blob/main/LICENSE.txt>`_ file for details.
 
 Other
 ------