fix md_mpx_format_adjuster.py script

.github/workflows/md_mpx_format_adjuster.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+"""
+Script to make Markdown files MPX compatible.
+
+This script scans Markdown files and escapes special characters (<, >, {, })
+to make them compatible with the MPX standard used in Docusaurus v3.
+
+This script complies with:
+    1) Pylint
+    2) Pydocstyle
+    3) Pycodestyle
+    4) Flake8
+"""
+
+import os
+import argparse
+import re
+
+def escape_mpx_characters(text):
+    """
+    Escape special characters in a text string for MPX compatibility.
+    Avoids escaping already escaped characters.
+
+    Args:
+        text: A string containing the text to be processed.
+
+    Returns:
+        A string with special characters (<, >, {, }) escaped, avoiding
+        double escaping.
+    """
+    # Regular expressions to find unescaped special characters
+    patterns = {
+        "<": r"(?<!\\)<",
+        ">": r"(?<!\\)>",
+        "{": r"(?<!\\){",
+        "}": r"(?<!\\)}"
+    }
+
+    # Replace unescaped special characters
+    for char, pattern in patterns.items():
+        text = re.sub(pattern, f"\\{char}", text)
+
+    return text
+
+def process_file(filepath):
+    """
+    Process a single Markdown file for MPX compatibility.
+
+    Args:
+        filepath: The path to the Markdown file to process.
+
+    Returns:
+        None, writes the processed content back to the file only if there are changes.
+    """
+    with open(filepath, 'r', encoding='utf-8') as file:
+        content = file.read()
+
+    # Escape MPX characters
+    new_content = escape_mpx_characters(content)
+
+    # Write the processed content back to the file only if there is a change
+    if new_content != content:
+        with open(filepath, 'w', encoding='utf-8') as file:
+            file.write(new_content)
+
+def main():
+    """
+    Main function to process all Markdown files in a given directory.
+
+    Scans for all Markdown files in the specified directory and processes each
+    one for MPX compatibility.
+
+    Args:
+        None
+
+    Returns:
+        None
+    """
+    parser = argparse.ArgumentParser(description="Make Markdown files MPX compatible.")
+    parser.add_argument(
+        "--directory",
+        type=str,
+        required=True,
+        help="Directory containing Markdown files to process."
+    )
+
+    args = parser.parse_args()
+
+    # Process each Markdown file in the directory
+    for root, _, files in os.walk(args.directory):
+        for file in files:
+            if file.lower().endswith(".md"):
+                process_file(os.path.join(root, file))
+
+if __name__ == "__main__":
+    main()

.github/workflows/push.yml

@@ -108,6 +108,9 @@ jobs:
           npm install typedoc-plugin-markdown
           npm i --save-dev @types/node
           npx typedoc --entryPoints src --out talawa-api-docs --plugin typedoc-plugin-markdown --theme markdown --entryPointStrategy expand
+
+      - name: Make Markdown Files MPX Compatible
+        run: python ./.github/workflows/md_mpx_format_adjuster.py --directory talawa-admin-docs
 
       - name: Checking doc updated
         id: DocUpdated
@@ -159,9 +162,9 @@ jobs:
       with:
         source_file: 'talawa-api-docs/'
         destination_repo: 'PalisadoesFoundation/talawa-docs'
-        destination_branch: 'testing-workflows'
+        destination_branch: 'develop'
         destination_folder: 'docs/'
-        user_email: '${{env.email}}'
+        user_email: '${{secrets.YOUR_EMAIL_SECRET}}'
         user_name: '${{github.actor}}'
         commit_message: 'Talawa API docs updated'
 

INSTALLATION.md

@@ -6,42 +6,45 @@ This document provides instructions on how to set up and start a running instanc
 
 <!-- TOC -->
 
+- [Table of Contents](#table-of-contents)
 - [Prerequisites](#prerequisites)
-  - [Install Node.js](#install-nodejs)
+  - [Install node.js](#install-nodejs)
   - [Install npm](#install-npm)
   - [Install TypeScript](#install-typescript)
-  - [Install Git](#install-git)
-  - [Setting Up This Repository](#setting-up-this-repository)
+  - [Install git](#install-git)
+  - [Setting up this repository](#setting-up-this-repository)
   - [Install the Required Packages](#install-the-required-packages)
-- [Installation with Docker](#installation-using-docker)
+- [Setting up .env file](#setting-up-env-file)
+- [Installation Using Docker](#installation-using-docker)
 - [Installation without Docker](#installation-without-docker)
   - [Install MongoDB](#install-mongodb)
     - [Setting up the mongoDB database](#setting-up-the-mongodb-database)
   - [Install Redis](#install-redis)
+    - [Performance Benefits](#performance-benefits)
     - [Setting Up Redis](#setting-up-redis)
-    - [Benchmark For Performance Benefits](#performance-benefits)
 - [Configuration](#configuration)
   - [The .env Configuration File](#the-env-configuration-file)
+  - [Changing the environment of talawa-api](#changing-the-environment-of-talawa-api)
   - [Generating Token Secrets](#generating-token-secrets)
-    - [Setting up ACCESS_TOKEN_SECRET in .env file](#setting-up-access_token_secret-in-env-file)
+    - [Setting up ACCESS\_TOKEN\_SECRET in .env file](#setting-up-access_token_secret-in-env-file)
       - [Linux](#linux)
       - [Windows](#windows)
-    - [Setting up REFRESH_TOKEN_SECRET in .env file](#setting-up-refresh_token_secret-in-env-file)
+    - [Setting up REFRESH\_TOKEN\_SECRET in .env file](#setting-up-refresh_token_secret-in-env-file)
   - [Configuring MongoDB](#configuring-mongodb)
-    - [Setting up the MONGODB_URL in .env file](#setting-up-the-mongodb_url-in-env-file)
-    - [Using the CLI to get the MONGODB_URL Connection String](#using-the-cli-to-get-the-mongodb_url-connection-string)
-    - [Using Microsoft Windows to get the MONGODB_URL Connection String](#using-microsoft-windows-to-get-the-mongodb_url-connection-string)
+    - [Setting up the MONGODB\_URL in .env file](#setting-up-the-mongodb_url-in-env-file)
+    - [Using the CLI to get the MONGODB\_URL Connection String](#using-the-cli-to-get-the-mongodb_url-connection-string)
+    - [Using Microsoft Windows to get the MONGODB\_URL Connection String](#using-microsoft-windows-to-get-the-mongodb_url-connection-string)
   - [Configuring Redis](#configuring-redis)
     - [For Local Setup (Linux and WSL)](#for-local-setup-linux-and-wsl)
     - [For Remote Setup (Redis Cloud)](#for-remote-setup-redis-cloud)
-  - [Setting up .env LAST_RESORT_SUPERADMIN_EMAIL parameter](#setting-up-env-last_resort_superadmin_email-parameter)
+  - [Setting up .env LAST\_RESORT\_SUPERADMIN\_EMAIL parameter](#setting-up-env-last_resort_superadmin_email-parameter)
   - [Configuring Google ReCAPTCHA](#configuring-google-recaptcha)
-    - [Setting up RECAPTCHA_SECRET_KEY in .env file](#setting-up-recaptcha_secret_key-in-env-file)
-    - [Setting up .env MAIL_USERNAME and MAIL_PASSWORD ReCAPTCHA Parameters](#setting-up-env-mail_username-and-mail_password-recaptcha-parameters)
+    - [Setting up RECAPTCHA\_SECRET\_KEY in .env file](#setting-up-recaptcha_secret_key-in-env-file)
+    - [Setting up .env MAIL\_USERNAME and MAIL\_PASSWORD ReCAPTCHA Parameters](#setting-up-env-mail_username-and-mail_password-recaptcha-parameters)
     - [Setting up .env SMTP Variables](#setting-up-env-smtp-variables)
   - [Setting up Logger configurations _(optional)_](#setting-up-logger-configurations-optional)
-    - [Setting up COLORIZE_LOGS in .env file](#setting-up-colorize_logs-in-env-file)
-    - [Setting up LOG_LEVEL in .env file](#setting-up-log_level-in-env-file)
+    - [Setting up COLORIZE\_LOGS in .env file](#setting-up-colorize_logs-in-env-file)
+    - [Setting up LOG\_LEVEL in .env file](#setting-up-log_level-in-env-file)
 - [Importing Sample Database](#importing-sample-database)
   - [Syntax:](#syntax)
   - [Examples:](#examples)
@@ -529,7 +532,7 @@ If the parameter value is set to `true`, you should be able to see colorized log
 
 ### Setting up LOG_LEVEL in .env file
 
-There are different logging levels that can be configured by setting this parameter. The severity order of levels are displayed numerically ascending from most important to least important.<br>
+There are different logging levels that can be configured by setting this parameter. The severity order of levels are displayed numerically ascending from most important to least important.<br></br>
 
 ```
  levels = {
@@ -543,8 +546,8 @@ There are different logging levels that can be configured by setting this parame
   }
 ```
 
-<br>On setting this parameter value, log messages are displayed in the console only if the `message.level` is less than or equal to setted `LOG_LEVEL`
-<br><br>
+<br>On setting this parameter value, log messages are displayed in the console only if the `message.level` is less than or equal to setted `LOG_LEVEL`</br>
+<br></br><br></br>
 For our application, the most appropriate setting is `LOG_LEVEL = info` since most of information logged on the console are error messages, warnings or info texts.
 
 # Importing Sample Database
@@ -620,7 +623,7 @@ By default talawa-api runs on `port 4000` on your system's localhost. It is avai
 
 If you navigate to the endpoint you and see a `JSON` response like this it means talawa-api is running successfully:
 
-        {"talawa-version":"v1","status":"healthy"}
+        `{"talawa-version":"v1","status":"healthy"}`
 
 GraphQL endpoint for handling `queries` and `mutations` is this:
 
@@ -745,11 +748,11 @@ These are some other factors to consider
 
 If port `4000` is not free on your system you can pass a custom environment variable named `PORT` to the script to make it use a different port on your system's localhost. Here's the syntax for it:
 
-        PORT=<CUSTOM_PORT_VALUE> npm run dev
+        `PORT=<CUSTOM_PORT_VALUE> npm run dev`
 
 where `<CUSTOM_PORT_VALUE>` is whatever value you want the `PORT` to be. Whatever you pass will be substituted as the value for port and talawa-api development server on that port. Syntax wise it looks like-
 
-        http://localhost:<CUSTOM_PORT_VALUE>/
+        `http://localhost:<CUSTOM_PORT_VALUE>/`
 
 For example:
 

src/typeDefs/README.md

@@ -14,24 +14,25 @@ Try to use alphabetical structuring whereever possible. This saves the mental ov
 
 # Documentation
 
-GraphQL allows developers to document their whole graphQL api within the schema. This is done using of a pair of `"""` symbols. Any text enclosed within these symbols becomes a description for the field it precedes.
+GraphQL allows developers to document their whole GraphQL API within the schema. This is done using a pair of `"""` symbols. Any text enclosed within these symbols becomes a description for the field it precedes.
 
-Here's a good example:-
+    Here's a good example:-
 
+    ```graphql
+    """
+    This is the GraphQL object type of a user.
+    """
+    type User {
         """
-        This is the graphQL object type of a user.
+        This is the unique id of the user.
         """
-        type User {
-            """
-            This is the unique id of the user.
-            """
-            id
+        id: String
 
-            """
-            This is userName of the user.
-            """
-            userName
-        }
+        """
+        This is userName of the user.
+        """
+        userName: String  # Add the type for userName
+    }
 
         """
         This is the graphQL input type of the input required for updating a user.