Fix typos and improve documentation clarity

Makefile

@@ -142,7 +142,7 @@ build_dummy_translations: extract_translations dummy_translations compile_transl
 validate_translations: build_dummy_translations detect_changed_source_translations ## validate translations
 
 install_transifex_client: ## Install the Transifex client
-	# Instaling client will skip CHANGELOG and LICENSE files from git changes
+	# Installing client will skip CHANGELOG and LICENSE files from git changes
 	# so remind the user to commit the change first before installing client.
 	git diff -s --exit-code HEAD || { echo "Please commit changes first."; exit 1; }
 	curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash

README.rst

@@ -12,7 +12,9 @@ Installation
 
 Starting from the Open edX Sumac release, the forum app is distributed via the `Tutor forum plugin <https://github.com/overhangio/tutor-forum>`__.
 
-The only prerequisite for installation is a working Open edX platform with `Tutor <https://docs.tutor.edly.io/>`__, on the Sumac release (v19+) or the `main branch <https://docs.tutor.edly.io/tutorials/main.html>`__. Enable the forum by running::
+The only prerequisite for installation is a working Open edX platform with `Tutor <https://docs.tutor.edly.io/>`__, on the Sumac release (v19+) or the `main branch <https://docs.tutor.edly.io/tutorials/main.html>`__. Enable the forum by running:
+
+.. code-block:: bash
 
     tutor plugins enable forum
     tutor local launch
@@ -22,19 +24,25 @@ The forum feature will then be automatically enabled in the Open edX platform, a
 Development
 ***********
 
-Run tests with::
+Run tests with:
+
+.. code-block:: bash
 
     make test-all       # run all tests
     make test           # run unit tests only
     make test-quality   # run quality tests only
     make test-e2e       # run end-to-end tests only
 
-When developing this application, it is recommended to clone this repository locally and mount it within the application containers::
+When developing this application, it is recommended to clone this repository locally and mount it within the application containers:
+
+.. code-block:: bash
 
     git clone [email protected]:openedx/forum.git
     tutor mounts add ./forum/
 
-Check that the forum repository is properly bind-mounted both at build- and run-time by running ``tutor mounts list``. It should output the following::
+Check that the forum repository is properly bind-mounted both at build- and run-time by running ``tutor mounts list``. It should output the following:
+
+.. code-block:: yaml
 
     - name: /home/path/to/forum
       build_mounts:
@@ -48,7 +56,9 @@ Check that the forum repository is properly bind-mounted both at build- and run-
       - service: openedx-dev
         container_path: /mnt/forum
 
-Re-build the openedx-dev image and launch the platform::
+Re-build the openedx-dev image and launch the platform:
+
+.. code-block:: bash
 
     tutor images build openedx-dev
     tutor dev launch
@@ -61,15 +71,19 @@ Deployment of the forum v2 application is gated by two course waffle flags. In a
 Forum v2 toggle
 ---------------
 
-In edx-platform, forum v2 is not enabled by default and edx-platform will keep communicating with the legacy forum app. To enable forum v2 in your Open edX platform, toggle the ``discussions.enable_forum_v2`` course waffle flag::
+In edx-platform, forum v2 is not enabled by default and edx-platform will keep communicating with the legacy forum app. To enable forum v2 in your Open edX platform, toggle the ``discussions.enable_forum_v2`` course waffle flag:
+
+.. code-block:: bash
 
     ./manage.py lms waffle_flag --create --everyone discussions.enable_forum_v2
 
 Note that Tutor enables this flag for all forum plugin users, such that you don't have to run this command yourself. If you wish to migrate your courses one by one to the new forum v2 app, you may create the corresponding "Waffle flag course override" objects in your LMS administration panel, at: ``http(s)://<LMS_HOST>/admin/waffle_utils/waffleflagcourseoverridemodel/``.
 
-⚠️⚠️⚠️ Even if the forum v2 toggle is not enabled, edx-platform will make a call to the forum v2 API in some edge cases. That's because edx-platform needs to determine whether it should use forum v2 or cs_comments_service, based on the value of some course waffle flag. In order to access the course wafffle flag, we need to determine the course ID of the current HTTP request. In some requests, the course ID is not available: only the thread ID or the comment ID is. Thus, edx-platform needs to fetch the course ID that is associated to the thread or comment. That information is stored either in MySQL or in MongoDB. Thus, edx-platform needs to call the forum v2 API.
+⚠️⚠️⚠️ Even if the forum v2 toggle is not enabled, edx-platform will make a call to the forum v2 API in some edge cases. That's because edx-platform needs to determine whether it should use forum v2 or cs_comments_service, based on the value of some course waffle flag. In order to access the course waffle flag, we need to determine the course ID of the current HTTP request. In some requests, the course ID is not available: only the thread ID or the comment ID is. Thus, edx-platform needs to fetch the course ID that is associated to the thread or comment. That information is stored either in MySQL or in MongoDB. Thus, edx-platform needs to call the forum v2 API.
+
+As a consequence, **the forum v2 app needs to have accurate MongoDB configuration settings even if you don't use forum v2**. In a Tutor installation, these settings are set to the right values. In other environments, the following Django settings must be set:
 
-As a consequence, **the forum v2 app needs to have accurate MongoDB configuration settings even if you don't use forum v2**. In a Tutor installation, these settings are set to the right values. In other environments, the following Django settings must be set::
+.. code-block:: python
 
     # Name of the MongoDB database in which forum data is stored
     FORUM_MONGODB_DATABASE = "cs_comments_service"
@@ -82,7 +96,9 @@ As a consequence, **the forum v2 app needs to have accurate MongoDB configuratio
 MySQL backend toggle
 --------------------
 
-To preserve the legacy behaviour of storing data in MongoDB, the forum v2 app makes it possible to keep using MongoDB as a data backend. However, it is strongly recommended to switch to the MySQL storage backend by toggling the ``forum_v2.enable_mysql_backend`` course waffle flag::
+To preserve the legacy behaviour of storing data in MongoDB, the forum v2 app makes it possible to keep using MongoDB as a data backend. However, it is strongly recommended to switch to the MySQL storage backend by toggling the ``forum_v2.enable_mysql_backend`` course waffle flag:
+
+.. code-block:: bash
 
     ./manage.py lms waffle_flag --create --everyone forum_v2.enable_mysql_backend
 
@@ -115,15 +131,21 @@ MongoDB data deletion
 
 After you have successfully migrated your course data from MySQL to MongoDB using the command above, you may delete your MongoDB data using the ``forum_delete_course_from_mongodb`` management command. This command deletes course data from MongoDB for the specified courses.
 
-Run the command with the course ID(s) as an argument::
+Run the command with the course ID(s) as an argument:
+
+.. code-block:: bash
 
    ./manage.py lms forum_delete_course_from_mongodb <course_id_1> <course_id_2>
 
-To delete data for all courses, run the command with the ``all`` argument::
+To delete data for all courses, run the command with the ``all`` argument:
+
+.. code-block:: bash
 
    ./manage.py lms forum_delete_course_from_mongodb all
 
-To try out changes before applying them, use the ``--dry-run`` option. For instance::
+To try out changes before applying them, use the ``--dry-run`` option. For instance:
+
+.. code-block:: bash
 
    ./manage.py lms forum_delete_course_from_mongodb all --dry-run
 
@@ -132,19 +154,23 @@ MongoDB Indexes
 
 To optimize MongoDB query performance, it is crucial to create database indexes. The command will create or update indexes and skip them if they already exist.
 
-To create or update MongoDB indexes, execute the following command::
+To create or update MongoDB indexes, execute the following command:
+
+.. code-block:: bash
 
     ./manage.py lms forum_create_mongodb_indexes
 
-Search Indicies
+Search Indices
 ---------------
 
 Based on your search backend i.e Elasticsearch or Meilisearch, the commands will populate search indexes.
 
 Initialize Forum Indices
 ========================
 
-To initialize search indices use ``initialize_forum_indices`` command. It allows you to force the creation of new indices even if they already exist::
+To initialize search indices use ``initialize_forum_indices`` command. It allows you to force the creation of new indices even if they already exist:
+
+.. code-block:: bash
 
     ./manage.py lms initialize_forum_indices
 

forum/api/commentables.py

@@ -16,7 +16,7 @@ def get_commentables_stats(course_id: str) -> dict[str, int]:
     Response:
         The threads count for the given course_id based on thread_type.
         e.g.
-        reponse = {'course': {'discussion': 1, 'question': 1}}
+        response = {'course': {'discussion': 1, 'question': 1}}
     """
     backend = get_backend(course_id)()
     return backend.get_commentables_counts_based_on_type(course_id)

forum/backends/backend.py

@@ -150,7 +150,7 @@ def prepare_thread(
         raise NotImplementedError
 
     @classmethod
-    def threads_presentor(
+    def threads_presenter(
         cls,
         thread_ids: list[str],
         user_id: str,

forum/backends/mongodb/api.py

@@ -685,7 +685,7 @@ def handle_threads_query(
                 collection = []
             else:
                 thread_ids = [str(thread["_id"]) for thread in threads]
-                collection = cls.threads_presentor(
+                collection = cls.threads_presenter(
                     thread_ids, user_id, course_id, count_flagged
                 )
 
@@ -734,7 +734,7 @@ def prepare_thread(
         }
 
     @classmethod
-    def threads_presentor(
+    def threads_presenter(
         cls,
         thread_ids: list[str],
         user_id: str,

forum/backends/mysql/api.py

@@ -772,7 +772,7 @@ def handle_threads_query(
         if len(threads) == 0:
             collection = []
         else:
-            collection = cls.threads_presentor(
+            collection = cls.threads_presenter(
                 threads, user_id, course_id, count_flagged
             )
 
@@ -815,7 +815,7 @@ def prepare_thread(
         }
 
     @classmethod
-    def threads_presentor(
+    def threads_presenter(
         cls,
         thread_ids: list[str],
         user_id: str,
@@ -891,13 +891,13 @@ def validate_object(model: str, obj_id: str) -> Any:
             raise exception if object does not exists.
             return object
         """
-        modelss = {
+        models = {
             "CommentThread": CommentThread,
             "Comment": Comment,
         }
 
         try:
-            instance = modelss[model].objects.get(pk=int(obj_id))
+            instance = models[model].objects.get(pk=int(obj_id))
         except ObjectDoesNotExist as exc:
             raise ObjectDoesNotExist from exc
 

forum/management/commands/forum_create_mongodb_indexes.py

@@ -20,5 +20,5 @@ def handle(self, *args: list[str], **kwargs: dict[str, str]) -> None:
         """
         BaseContents().create_indexes()
         self.stdout.write(
-            self.style.SUCCESS("Created/Updated Mongodb indexes successfuly.")
+            self.style.SUCCESS("Created/Updated Mongodb indexes successfully.")
         )

forum/utils.py

@@ -93,7 +93,7 @@ def get_str_value_from_collection(collection: dict[str, Any], key: str) -> str:
     try:
         value = str(collection[key])
     except (TypeError, ValueError, KeyError) as exception:
-        raise ValueError("Invalud Value") from exception
+        raise ValueError("Invalid Value") from exception
     return value
 
 

forum/views/subscriptions.py

@@ -41,10 +41,10 @@ def post(self, request: Request, user_id: str) -> Response:
         """
         request_data = request.data
         try:
-            serilized_data = create_subscription(user_id, request_data["source_id"])
+            serialized_data = create_subscription(user_id, request_data["source_id"])
         except ForumV2RequestError as e:
             return Response(data={"error": str(e)}, status=status.HTTP_400_BAD_REQUEST)
-        return Response(data=serilized_data, status=status.HTTP_200_OK)
+        return Response(data=serialized_data, status=status.HTTP_200_OK)
 
     def delete(self, request: Request, user_id: str) -> Response:
         """
@@ -62,10 +62,10 @@ def delete(self, request: Request, user_id: str) -> Response:
         """
         try:
             params = request.query_params
-            serilized_data = delete_subscription(user_id, params["source_id"])
+            serialized_data = delete_subscription(user_id, params["source_id"])
         except ForumV2RequestError as e:
             return Response(data={"error": str(e)}, status=status.HTTP_400_BAD_REQUEST)
-        return Response(data=serilized_data, status=status.HTTP_200_OK)
+        return Response(data=serialized_data, status=status.HTTP_200_OK)
 
 
 class UserSubscriptionAPIView(APIView):
@@ -93,12 +93,12 @@ def get(self, request: Request, user_id: str) -> Response:
         """
         params = request.GET.dict()
         try:
-            serilized_data = get_user_subscriptions(
+            serialized_data = get_user_subscriptions(
                 user_id, params["course_id"], params
             )
         except ForumV2RequestError as e:
             return Response(data={"error": str(e)}, status=status.HTTP_400_BAD_REQUEST)
-        return Response(data=serilized_data, status=status.HTTP_200_OK)
+        return Response(data=serialized_data, status=status.HTTP_200_OK)
 
 
 class ThreadSubscriptionAPIView(APIView):

tests/e2e/test_search_es.py

@@ -741,7 +741,7 @@ def test_spelling_correction_with_mush_clause(
 ) -> None:
     """
     Test the spelling correction feature & mush clause in the search.
-    Verifies the even if the text matches with the threds it should also consider other
+    Verifies the even if the text matches with the threads it should also consider other
     params in the search i.e course_id
     """
     backend = patched_get_backend()

tests/test_views/test_search.py

@@ -693,7 +693,7 @@ def test_spelling_correction_with_mush_clause(
 ) -> None:
     """
     Test the spelling correction feature & mush clause in the search.
-    Verifies the even if the text matches with the threds it should also consider other
+    Verifies the even if the text matches with the threads it should also consider other
     params in the search i.e course_id
     """
     backend = patched_get_backend()

tests/test_views/test_threads.py

@@ -73,7 +73,7 @@ def create_comments_in_a_thread(backend: Any, thread_id: str) -> tuple[str, str]
 
 
 def test_update_thread(api_client: APIClient, patched_get_backend: Any) -> None:
-    """Test updaing a thread."""
+    """Test updating a thread."""
     backend = patched_get_backend
     user_id, thread_id = setup_models(backend=backend)
     response = api_client.put_json(