Merge pull request #862 from gautam-divyanshu/docs_info

Documenatation workflow guide added

docs/documentation_generation_guide/admin_documentation_flow.md

@@ -0,0 +1,49 @@
+---
+title: Admin Documentation Flow
+id: admin_documentation_flow
+---
+
+# Admin Documentation Flow
+
+This section explains the process of generating documentation for Talawa Admin and updating the Talawa Docs website.
+
+- ![DocsWorkFlow](/img/docs_workflow.png)
+
+## Steps:
+
+1. Clone the `talawa-admin` repository into the `talawa-docs` directory.
+   ```bash
+   git clone --depth=1 --branch develop https://github.com/adi790uu/talawa-admin.git
+   ```
+
+2. Create a new directory inside `talawa-docs` for admin documentation.
+   ```bash
+   mkdir -p docs/talawa-admin-docs
+   ```
+
+3. Enter the cloned `talawa-admin` repository.
+   ```bash
+   cd talawa-admin
+   ```
+
+4. Generate documentation using `Typedoc` inside the `talawa-admin-docs` directory.
+   ```bash
+   npm install --global typedoc
+   npm install typedoc-plugin-markdown
+   npx typedoc --entryPoints src/components src/screens --out talawa-admin-docs --plugin typedoc-plugin-markdown --entryPointStrategy expand
+   ```
+
+5. Recursively copy the generated documentation to the `docs/talawa-admin-docs` folder.
+   ```bash
+   cp -r talawa-admin/talawa-admin-docs/* docs/talawa-admin-docs/
+   ```
+
+6. Clean up the cloned repository and push the updated documentation.
+   ```bash
+   rm -rf talawa-admin
+   git add .
+   git commit -m "Updated talawa admin docs"
+   git pull --rebase origin develop
+   git push -u origin develop
+   ```
+

docs/documentation_generation_guide/api_documentation_flow.md

@@ -0,0 +1,49 @@
+---
+title: API Documentation Flow
+id: api_documentation_flow
+---
+
+# API Documentation Flow
+
+This section explains the process of generating documentation for Talawa API and updating the Talawa Docs website.
+
+- ![DocsWorkFlow](/img/docs_workflow.png)
+
+## Steps:
+
+1. Clone the `talawa-api` repository into the `talawa-docs` directory.
+   ```bash
+   git clone --depth=1 --branch develop https://github.com/PalisadoesFoundation/talawa-api.git
+   ```
+
+2. Create a new directory inside `talawa-docs` for API documentation.
+   ```bash
+   mkdir -p docs/talawa-api-docs
+   ```
+
+3. Enter the cloned `talawa-api` repository.
+   ```bash
+   cd talawa-api
+   ```
+
+4. Generate documentation using `Typedoc` inside the `talawa-api-docs` directory.
+   ```bash
+   npm install --global typedoc
+   npm install typedoc-plugin-markdown
+   npx typedoc --entryPoints src --out talawa-api-docs --plugin typedoc-plugin-markdown --entryPointStrategy expand
+   ```
+
+5. Recursively copy the generated documentation to the `docs/talawa-api-docs` folder.
+   ```bash
+   cp -r talawa-api/talawa-api-docs/* docs/talawa-api-docs/
+   ```
+
+6. Clean up the cloned repository and push the updated documentation.
+   ```bash
+   rm -rf talawa-api
+   git add .
+   git commit -m "Updated talawa api docs"
+   git pull --rebase origin develop
+   git push -u origin develop
+   ```
+

docs/documentation_generation_guide/documentation_workflow_overview.md

@@ -0,0 +1,17 @@
+---
+title: Documentation Workflow Overview
+id: documentation_workflow
+---
+
+# Documentation Workflow Overview
+
+This guide describes how documentation is generated, copied, and rendered for Talawa Admin and API using GitHub Actions and Typedoc.
+
+## Overview
+
+The documentation is generated from TSDoc comments and is hosted on the Talawa Docs website using **Docusaurus**. The workflow is automated via GitHub Actions and involves the following key steps:
+
+- Cloning the Talawa Admin and API repositories.
+- Generating documentation using `Typedoc`.
+- Recursively copying the documentation to the appropriate directories.
+- Rendering the documentation to the Talawa Docs website.

docs/documentation_generation_guide/github_actions_tsdoc_validation.md

@@ -0,0 +1,30 @@
+---
+title: GitHub Actions for TSDoc Validation
+id: github_actions_tsdoc_validation
+---
+
+# GitHub Actions for TSDoc Validation
+
+We have implemented a **GitHub Action** to validate TSDoc comments during commits or pull requests. This ensures that new or modified code adheres to documentation standards.
+
+## Steps:
+
+1. A custom script or plugin checks the deltas in the pull requests or commits.
+2. The script is integrated into the linting process to target modified code segments.
+3. The script ensures that the modified or newly added code includes valid TSDoc comments.
+
+## Example Script
+
+```bash
+const fs = require('fs');
+const path = require('path');
+
+function findTsxFiles(dir) {
+    // Logic to find files and check for TSDoc comments
+}
+
+function containsTsDocComment(filePath) {
+    // Logic to validate TSDoc comments
+}
+
+run();

docs/documentation_generation_guide/tsdoc_guide.md

@@ -0,0 +1,29 @@
+---
+title: TSDoc comments in Talawa API & Admin
+id: tsdoc_guide
+---
+
+
+
+# Using TSDoc in Talawa
+
+TSDoc is a documentation standard for TypeScript projects that allows developers to write comments directly in the code. These comments can then be converted into comprehensive documentation using tools like Typedoc. In Talawa Admin and API, TSDoc is used extensively to document the various components, classes, functions, and methods.
+
+## How TSDoc Is Implemented in Talawa
+
+TSDoc comments are added directly above the relevant code elements (such as functions, classes, or methods) to explain their purpose and functionality. The structure of a TSDoc comment is standardized to make it easier for developers to understand the code and how to use it.
+
+### Example TSDoc Comment
+
+Here is an example of a TSDoc comment used in the Talawa Admin project:
+
+```ts
+/**
+ * Fetches a list of users from the database.
+ *
+ * @param limit - Maximum number of users to retrieve
+ * @returns An array of user objects
+ */
+function getUsers(limit: number): User[] {
+  // Function implementation
+}

docs/documentation_generation_guide/why_mdx_required.md

@@ -0,0 +1,20 @@
+---
+title: Why MDX Compatibility Script is Necessary
+id: why_mdx_compatibility_script
+---
+
+# Why MDX Compatibility Script is Necessary
+
+`md_mdx_format_adjuster.py`
+
+When working with **Docusaurus v3**, it’s essential to ensure that Markdown files are compatible with MDX (Markdown with JSX). MDX allows us to integrate React components directly within our markdown, providing greater flexibility and interactivity in our documentation. However, certain characters (`<`, `>`, `{`, `}`) in Markdown files can cause issues when interpreted as JSX syntax, leading to rendering errors.
+
+## Purpose of the Script
+
+The provided Python script addresses this problem by:
+
+- **Escaping Special Characters**: It scans Markdown files and automatically escapes the problematic characters `<`, `>`, `{`, and `}`, ensuring that the files are MDX-compatible.
+
+- **Maintaining Readability**: By avoiding double escaping, the script ensures that the Markdown remains clean and readable.
+
+- **Automating the Process**: It can be run on an entire directory of Markdown files, streamlining the process of making large documentation projects MDX-ready.

sidebars.js

@@ -216,6 +216,22 @@ const sidebars = {
         "design/ux/ux-design-system",
       ],
     },
+    {
+      type: "category",
+      label: "Documentation Generation Guide",
+      link: {
+        type: "generated-index",
+      },
+      collapsed: true,
+      items: [
+        "documentation_generation_guide/documentation_workflow",
+        "documentation_generation_guide/admin_documentation_flow",
+        "documentation_generation_guide/api_documentation_flow",
+        "documentation_generation_guide/why_mdx_compatibility_script",
+        "documentation_generation_guide/tsdoc_guide",
+        "documentation_generation_guide/github_actions_tsdoc_validation",
+      ],
+    },
     {
       type: "category",
       label: "Internships",