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

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,11 @@ 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).
+- 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="_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.
+- Log in to your WordPress admin dashboard, navigate to the Plugins menu in the sidebar, click "Add New," upload the ZIP version of this project, and 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 +46,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 +59,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,17 @@ 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).
+- 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="_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.
+- Log in to your WordPress admin dashboard, navigate to the Plugins menu in the sidebar, click "Add New," upload the ZIP version of this project, and 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 +79,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,14 +1,28 @@
 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`_
+- `Steps`_
+- `Next Steps`_
+
+Requisites
+-----------
+
+Have access to a Django admin dashboard for your Open edX platform.
+
+Steps
+------
 
 #. 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.
 
@@ -27,4 +41,4 @@ You will learn how to create an Open edX Application for filling out the form in
 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

@@ -5,10 +5,17 @@ The Open edX WooCommerce Plugin uses Enrollment Request to manage the enrollment
 
 In this section, you will learn how to create an Enrollment Request manually.
 
+Index
+-------
+- `Requisites`_
+- `Steps`_
+- `About 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 don't 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
 ------
@@ -18,25 +25,44 @@ Steps
     .. 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.
 
     .. 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.
+And that's it!
 
-* Enter the email of the user who will be used in the request.
+About the Enrollment Request View
+----------------------------------
 
-* Select a Course Mode that the course has.
+Fields
+^^^^^^^
+- Course ID: the ID from your Open edX platform course. e.g. course-v1:edX+DemoX+Demo_Course. 
 
-* 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).
+- User Email: the user's email address that will be used in the request.
 
-* If this request has an Order associated, you can fill in the "WC Order ID" field.
+- 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.
 
-* If you select to use the force flag, the action will not consider the course enrollment dates.
+- Request type: If you select **Enroll**, you will create an enrollment, and if you choose **Un-enroll**, you will set a soft unenrollment (enrollment with status inactive) if you update in Open edX.
 
-* Creating a "course enrollment allowed" if the user doesn't exist is available only if you have a release greater than Palm.
+- WC Order ID: This field will fill automatically if your request has an order associated with it; you can use it to navigate from the Enrollment Request to the Order.
 
-And that's it!
+Flags
+^^^^^^
+
+- Use the "force" flag: if you select this, the action will not consider the course enrollment end dates.
+
+- Creating a course enrollment allowed if the user doesn't 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.
+
+Buttons
+^^^^^^^^
+
+- 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.
+
+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
+------
+- `Steps`_
+- `Next Steps`_
+
+Steps
+------
+
+- 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 product
+=========================================
+
+You will learn how to refund an Open edX product from a WooCommerce order.
+
+Index
+------
+- `Refund an Open edX course product`_
+- `Expected behavior`_
+- `Next Steps`_
+
+Refund an Open edX course product
+----------------------------------
+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 unenrollment 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
 ------