reformat: RST syntax

This will clean up the README file to follow the RST format, fixed some typos and improved readability.

README.rst

@@ -1,42 +1,64 @@
-Course Discovery plugin for `Tutor <https://docs.tutor.edly.io>`_
-=====================================================================
+Course Discovery plugin for `Tutor`_
+====================================
 
-This is a plugin for `Tutor <https://docs.tutor.edly.io>`_ that integrates the `Course Discovery <https://github.com/edx/course-discovery/>`__ application in an Open edX platform. it is useful for integration with, for example, `Ecommerce <https://github.com/edx/ecommerce>`__ or an external course catalog.
+This is a plugin for `Tutor`_ that integrates the `Course Discovery`_ application in an Open edX platform.
+it is useful for integration with, for example, `Ecommerce`_ or an external course catalog.
+
+
+.. _Tutor: https://docs.tutor.edly.io
+.. _Course Discovery: https://github.com/edx/course-discovery/
+.. _Ecommerce: https://github.com/edx/ecommerce
 
 Installation
 ------------
 
-This plugin requires tutor>=3.6.0. If you have installed tutor from a pre-compiled binary, it already comes bundled with the discovery plugin. Otherwise::
+This plugin requires ``tutor>=3.6.0``. If you have installed tutor from a pre-compiled binary,
+it already comes bundled with the discovery plugin. Otherwise:
+
+.. code-block:: bash
+
 
     tutor plugins install discovery
 
-Then, to enable this plugin, run::
+Then, to enable this plugin, run:
+
+.. code-block:: bash
 
     tutor plugins enable discovery
 
-Restart and initialize your platform with::
+Restart and initialize your platform with:
+
+.. code-block:: bash
 
-    tutor local launch
+    tutor dev|local|k8s launch
 
 Operations
 ----------
 
 Creating a user
 ~~~~~~~~~~~~~~~
 
-The discovery user interface will be available at http://discovery.local.edly.io for a local test instance, and at ``DISCOVERY_HOST`` (by default: http(s)://discovery.<your lms host>) in production. In order to run commands from the UI, a user must be created::
+The discovery user interface will be available at http://discovery.local.edly.io for a local test instance,
+and at ``DISCOVERY_HOST`` (by default: http(s)://discovery.<your lms host>) in production. To run
+commands from the UI, a user must be created:
+
+.. code-block:: bash
 
     tutor local run discovery ./manage.py createsuperuser
 
-Then, you must login with this user at http://discovery.local.edly.io/admin.
+Then, you must log in with this user at http://discovery.local.edly.io/admin.
 
-Alternatively, you can login with oauth2 using a pre-existing user created on the LMS/CMS by accessing http(s)://discovery.<your lms host>/login. To do so, the proper domain names must exist and point to the production server.
+Alternatively, you can log in with oauth2 using a pre-existing user created on the LMS/CMS by accessing
+http(s)://discovery.<your lms host>/login. To do so, the proper domain names must exist and point to
+the production server.
 
 Index configuration
 ~~~~~~~~~~~~~~~~~~~
 
-Discovery uses separate indices for different models (the names are: course, course_run, person and program by default). And you can overwrite theses
-names by configuring ``DISCOVERY_INDEX_OVERRIDES``::
+Discovery uses separate indices for different models (the names are: course, course_run, person, and
+program by default). And you can overwrite these names by configuring ``DISCOVERY_INDEX_OVERRIDES``:
+
+.. code-block:: yml
 
     DISCOVERY_INDEX_OVERRIDES:
       course_discovery.apps.course_metadata.search_indexes.documents.course: your-course-index-name
@@ -47,35 +69,50 @@ names by configuring ``DISCOVERY_INDEX_OVERRIDES``::
 Re-indexing courses
 ~~~~~~~~~~~~~~~~~~~
 
-While running tutor in production mode::
+While running tutor in production mode:
+
+.. code-block:: bash
 
     tutor local run discovery ./manage.py refresh_course_metadata --partner_code=openedx
     tutor local run discovery ./manage.py update_index --disable-change-limit
 
-While running tutor in development mode::
+While running tutor in development mode:
+
+.. code-block:: bash
 
     tutor dev run discovery ./manage.py refresh_course_metadata --partner_code=dev
     tutor dev run discovery ./manage.py update_index --disable-change-limit
 
 Caching programs
 ~~~~~~~~~~~~~~~~
 
-In order to cache programs in the LMS, you will need to manually create a catalog integration. Make sure you use staff user for the below command. If ``lms_catalog_service_user`` is not a staff user, then make it a staff user in your LMS User model. This step should be performed just once::
+To cache programs in the LMS, you will need to manually create a catalog integration.
+Make sure you use staff user for the below command. If ``lms_catalog_service_user`` is not a staff user,
+then make it a staff user in your LMS User model. This step should be performed just once:
+
+.. code-block:: bash
 
     tutor local run lms ./manage.py lms create_catalog_integrations --enabled \
         --internal_api_url="" \
         --service_username=lms_catalog_service_user
 
-Then run the below command, this command will cause errors every time as it tries to cache programs from all sites that are added to your LMS sites model::
+Then run the below command, this command will cause errors every time it tries to cache programs
+from all sites that are added to your LMS sites model:
+
+.. code-block:: bash
 
     tutor local run lms ./manage.py lms cache_programs
 
-Above command will give some errors as it tries to cache programs for all sites. So make use of an extra argument to the command .i.e. ``--domain``.
-While running tutor in production mode::
+The above command will give some errors as it tries to cache programs for all sites. So make use of an
+extra argument to the command. i.e. ``--domain``. While running tutor in production mode:
+
+.. code-block:: bash
 
     tutor local run lms ./manage.py lms cache_programs --domain="local.edly.io"
 
-While running tutor in development mode::
+While running tutor in development mode:
+
+.. code-block:: bash
 
     tutor dev run lms ./manage.py lms cache_programs --domain="local.edly.io:8000"
 
@@ -84,12 +121,21 @@ This last step should be performed every time you create new or make changes to
 Show Programs Tab
 ~~~~~~~~~~~~~~~~~
 
-In order to make ``Programs`` tab work in the LMS dashboard, users will need to manually create an entry in ``Programs api config`` model in LMS Admin Panel. Go to http://local.edly.io/admin/programs/programsapiconfig/. Add ``Marketing path`` equal to ``/programs`` and enable it. Then Programs tab will be shown on the LMS where users can view their registered programs. It will show like as in below picture.
+To make the ``Programs`` tab work in the LMS dashboard, users will need to manually create an entry
+in the ``Programs api config`` model in the LMS Admin Panel. Go to http://local.edly.io/admin/programs/programsapiconfig/.
+Add ``Marketing path`` equal to ``/programs`` and enable it. Then Programs tab will be shown on the LMS
+where users can view their registered programs. It will show like in the below picture.
 
 .. image:: https://github.com/overhangio/tutor-discovery/assets/122095701/e0224011-adc0-41e4-a104-af4cb0c24b82
     :alt: Programs Tab on LMS dashboard
 
-In the above image, User can see explore programs button which is pointing to ``http://localhost:8080/programs`` by default. This link does not exist. So, users can change this link to their custom build marketing site url to show all programs there. This can be done by modifying ``Site Configurations`` model in LMS Admin Panel. Go to http://local.edly.io/admin/site_configuration/siteconfiguration/. Open respective LMS site configuration and add below dict in ``site values`` field like below image::
+In the above image, the user can see explore programs button which is pointing to ``http://localhost:8080/programs`` by default.
+This link does not exist. So, users can change this link to their custom-built marketing site URL to show all programs there.
+This can be done by modifying the ``Site Configurations`` model in the LMS Admin Panel. Go to
+http://local.edly.io/admin/site_configuration/siteconfiguration/. Open the respective LMS site configuration and add the below
+dictionary in ``site values`` field like the below image:
+
+.. code-block:: python
 
     "MKTG_URLS": {
         "ROOT": "https://custom-marketing-site-here.com"
@@ -101,50 +147,70 @@ In the above image, User can see explore programs button which is pointing to ``
 Install extra requirements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In order to install extra requirements, use DISCOVERY_EXTRA_PIP_REQUIREMENTS and re-build the docker image.::
+To install extra requirements, use DISCOVERY_EXTRA_PIP_REQUIREMENTS and re-build the docker image.
 
-  tutor config save \
-    --set 'DISCOVERY_EXTRA_PIP_REQUIREMENTS=["git+https://github.com/myusername/myplugin"]'
+.. code-block:: bash
 
-Then, build the image, pointing to your fork if necessary::
+  tutor config save --set 'DISCOVERY_EXTRA_PIP_REQUIREMENTS=["git+https://github.com/myusername/myplugin"]'
+
+Then, build the image, pointing to your fork if necessary:
+
+.. code-block:: bash
 
   tutor images build discovery
 
 Debugging
 ---------
 
-To debug the course discovery service, you are encouraged to mount the course-discovery repo from the host in the development container:
+To debug the course discovery service, you are encouraged to mount the course-discovery repo from the host
+in the development container:
+
+.. code-block:: bash
 
     tutor dev start --mount /path/to/course-discovery/ discovery
 
-You can then access the development server at http://discovery.local.edly.io:8381. Feel free to add breakpoints (``import pdb; pdb.set_trace()``) anywhere in your source code to debug your application.
+You can then access the development server at http://discovery.local.edly.io:8381. Feel free to add breakpoints
+(``import pdb; pdb.set_trace()``) anywhere in your source code to debug your application.
+
+Once a local repository is mounted in the image, you will have to install nodejs dependencies and collect static assets:
 
-Once a local repository is mounted in the image, you will have to install nodejs dependencies and collect static assets::
+.. code-block:: bash
 
     tutor dev run discovery npm install --development
     tutor dev run discovery make static.dev
 
-Troubleshooting
----------------
-
-This Tutor plugin is maintained by Muhammad Faraz Maqsood from `Edly <https://edly.io/>`__. Community support is available from the official `Open edX forum <https://discuss.openedx.org>`__. Do you need help with this plugin? See the `troubleshooting <https://docs.tutor.edly.io/troubleshooting.html>`__ section from the Tutor documentation.
-
 
 `Max retries exceeded with url`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 When running in production with HTTPS enabled, you may face this error during the `init` phase of `tutor local launch`:
 
-```
-requests.exceptions.ConnectionError: HTTPSConnectionPool(host='<LMS_HOST>', port=443): Max retries exceeded with url: /api/courses/v1/courses/?page=1&page_size=10&username=discovery
-```
+.. code-block:: log
 
-This error may be due to an incorrect DNS resolution of the LMS DNS record. With some cloud providers (for instance: [DigitalOcean](https://digitalocean.com/)) the `/etc/hosts` file on the host automatically contains the following entry::
+    requests.exceptions.ConnectionError: HTTPSConnectionPool(host='<LMS_HOST>', port=443): Max retries exceeded with url: /api/courses/v1/courses/?page=1&page_size=10&username=discovery
+
+This error may be due to an incorrect DNS resolution of the LMS DNS record. With some cloud providers
+(for instance: `DigitalOcean <https://digitalocean.com/>`__) the `/etc/hosts` file on the host automatically
+contains the following entry:
+
+.. code-block:: bash
 
     127.0.1.1 <LMS HOST>
 
 This entry may be present if you named your server with the LMS hostname.
 
+Troubleshooting
+---------------
+
+This Tutor plugin is maintained by Muhammad Faraz Maqsood from `Edly`_.
+Community support is available from the official `Open edX forum`_.
+Do you need help with this plugin? See the `troubleshooting`_
+section from the Tutor documentation.
+
+.. _Edly: https://edly.io/
+.. _Open edX forum: https://discuss.openedx.org
+.. _troubleshootin: https://docs.tutor.edly.io/troubleshooting.html
+
 License
 -------