Skip to content

Commit

Permalink
Updated operation documentation (#3475)
Browse files Browse the repository at this point in the history
* Updated operation documentation

* Updated operation documentation

* Upgraded docusaurus
palisadoes authored Jan 28, 2025
1 parent 3c85403 commit 008904a
Showing 9 changed files with 178 additions and 108 deletions.
8 changes: 8 additions & 0 deletions docs/docs/docs/developer-resources/introduction.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
id: introduction
title: Introduction
slug: /developer-resources/introduction
sidebar_position: 1
---

Welcome to Talawa-Admin
12 changes: 12 additions & 0 deletions docs/docs/docs/developer-resources/operation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
id: operation
title: Operation
slug: /developer-resources/operation
sidebar_position: 3
---

## Introduction

This section covers how Talawa Admin operates

Coming soon.
65 changes: 65 additions & 0 deletions docs/docs/docs/developer-resources/testing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
---
id: testing
title: Testing
slug: /developer-resources/testing
sidebar_position: 4
---

## Introduction

It is important to test our code. If you are a contributor, please follow these steps.

### Running tests

You can run the tests for `talawa-admin` using this command:

```bash
npm run test

```

### Debugging tests

You can see the output of failing tests in broswer by running `jest-preview` package before running your tests

```bash
npm run jest-preview
npm run test

```

You don't need to re-run the `npm run jest-preview` command each time, simply run the `npm run test` command if the Jest Preview server is already running in the background, it'll automatically detect any failing tests and show the preview at `http://localhost:3336` as shown in this screenshot -

![Debugging Test Demo](../../../static/img/markdown/installation/jest-preview.webp)

### Linting code files

You can lint your code files using this command:

```bash
npm run lint:fix
```

### Husky for Git Hooks

We are using the package `Husky` to run git hooks that run according to different git workflows.

##### pre-commit hook

We run a pre-commit hook which automatically runs code quality checks each time you make a commit and also fixes some of the issues. This way you don't have to run them manually each time.

If you don't want these pre-commit checks running on each commit, you can manually opt out of it using the `--no-verify` flag with your commit message as shown:-

```bash
git commit -m "commit message" --no-verify
```

##### post-merge hook

We are also running a post-merge(post-pull) hook which will automatically run "npm install" only if there is any change made to pakage.json file so that the developer has all the required dependencies when pulling files from remote.

If you don't want this hook to run, you can manually opt out of this using the `--no-verify` flag while using the merge command `git pull`:

```bash
git pull --no-verify
```
10 changes: 10 additions & 0 deletions docs/docs/docs/developer-resources/troubleshooting.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
id: troubleshooting
title: Troubleshooting
slug: /developer-resources/troubleshooting
sidebar_position: 5
---

## Introduction

Coming soon.
100 changes: 0 additions & 100 deletions docs/docs/docs/getting-started/installation.md
Original file line number Diff line number Diff line change
@@ -267,103 +267,3 @@ REACT_APP_RECAPTCHA_SITE_KEY="this_is_the_recaptcha_key"
#### Setting up Compiletime and Runtime logs

Set the `ALLOW_LOGS` to "YES" if you want warnings , info and error messages in your console or leave it blank if you dont need them or want to keep the console clean

## Post Configuration Steps

It's now time to start Talawa-Admin and get it running
### Running Talawa-Admin
Run the following command to start `talawa-admin` development server:
```bash
npm run serve
```
### Accessing Talawa-Admin
By default `talawa-admin` runs on port `4321` on your system's localhost. It is available on the following endpoint:

```
http://localhost:4321/
```

If you have specified a custom port number in your `.env` file, Talawa-Admin will run on the following endpoint:

```
http://localhost:\$\{\{customPort\}\}/
```

Replace `${{customPort}}` with the actual custom port number you have configured in your `.env` file.

### Talawa-Admin Registration

The first time you navigate to the running talawa-admin's website you'll land at talawa-admin registration page. Sign up using whatever credentials you want and create the account. Make sure to remember the email and password you entered because they'll be used to sign you in later on.
### Talawa-Admin Login
Now sign in to talawa-admin using the `email` and `password` you used to sign up.
## Testing
It is important to test our code. If you are a contributor, please follow these steps.
### Running tests
You can run the tests for `talawa-admin` using this command:
```bash
npm run test
```
### Debugging tests
You can see the output of failing tests in broswer by running `jest-preview` package before running your tests
```bash
npm run jest-preview
npm run test
```
You don't need to re-run the `npm run jest-preview` command each time, simply run the `npm run test` command if the Jest Preview server is already running in the background, it'll automatically detect any failing tests and show the preview at `http://localhost:3336` as shown in this screenshot -
![Debugging Test Demo](../../../static/img/markdown/installation/jest-preview.webp)
### Linting code files
You can lint your code files using this command:
```bash
npm run lint:fix
```
### Husky for Git Hooks
We are using the package `Husky` to run git hooks that run according to different git workflows.
##### pre-commit hook
We run a pre-commit hook which automatically runs code quality checks each time you make a commit and also fixes some of the issues. This way you don't have to run them manually each time.

If you don't want these pre-commit checks running on each commit, you can manually opt out of it using the `--no-verify` flag with your commit message as shown:-
```bash
git commit -m "commit message" --no-verify
```
##### post-merge hook
We are also running a post-merge(post-pull) hook which will automatically run "npm install" only if there is any change made to pakage.json file so that the developer has all the required dependencies when pulling files from remote.
If you don't want this hook to run, you can manually opt out of this using the `--no-verify` flag while using the merge command `git pull`:

```bash
git pull --no-verify
```
67 changes: 67 additions & 0 deletions docs/docs/docs/getting-started/operation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
---
id: operation
title: Operation, Registration & Login
slug: /operation
sidebar_position: 2
---

This page outlines how to successfully operate the application

## Operation

Operation of the application requires these steps.

### Running Talawa-Admin

Run the following command to start `talawa-admin` development server:

```bash
npm run serve

```

### Accessing Talawa-Admin

By default `talawa-admin` runs on port `4321` on your system's localhost. It is available on the following endpoint:

```
http://localhost:4321/
```

If you have specified a custom port number in your `.env` file, Talawa-Admin will run on the following endpoint:

```
http://localhost:{{customPort}}/
```

Replace `{{customPort}}` with the actual custom port number you have configured in your `.env` file.

## Registration

The first time you navigate to the running talawa-admin's website you'll land at talawa-admin registration page. Sign up using whatever credentials you want and create the account. Make sure to remember the email and password you entered because they'll be used to sign you in later on.

## Login

The login process is different depending on the scenario

### Normal Login

Now sign in to talawa-admin using the `email` and `password` you used to sign up.

### First Time API Administrator Login

The email address and password are defined these API environment variables:

1. `API_ADMINISTRATOR_USER_EMAIL_ADDRESS`
1. `API_ADMINISTRATOR_USER_NAME`
1. `API_ADMINISTRATOR_USER_PASSWORD`

In a development environment, the defaults are:

1. `API_ADMINISTRATOR_USER_EMAIL_ADDRESS`=administrator@email.com
1. `API_ADMINISTRATOR_USER_NAME`=administrator
1. `API_ADMINISTRATOR_USER_PASSWORD`=password
10 changes: 5 additions & 5 deletions docs/package.json
Original file line number Diff line number Diff line change
@@ -15,8 +15,8 @@
"typecheck": "tsc"
},
"dependencies": {
"@docusaurus/core": "3.6.3",
"@docusaurus/preset-classic": "3.6.3",
"@docusaurus/core": "^3.7.0",
"@docusaurus/preset-classic": "^3.7.0",
"@mdx-js/react": "^3.0.0",
"clsx": "^2.0.0",
"docusaurus": "^1.14.7",
@@ -25,9 +25,9 @@
"react-dom": "^18.0.0"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "3.6.3",
"@docusaurus/tsconfig": "3.6.3",
"@docusaurus/types": "3.6.3",
"@docusaurus/module-type-aliases": "^3.7.0",
"@docusaurus/tsconfig": "^3.7.0",
"@docusaurus/types": "^3.7.0",
"typescript": "~5.6.2"
},
"browserslist": {
11 changes: 9 additions & 2 deletions docs/sidebars.ts
Original file line number Diff line number Diff line change
@@ -25,8 +25,15 @@ const sidebars: SidebarsConfig = {

{
type: 'category',
label: 'Plugins',
items: [{ type: 'autogenerated', dirName: 'docs/plugins' }],
label: 'Developer Resources',
items: [
{ type: 'autogenerated', dirName: 'docs/developer-resources' },
{
type: 'category',
label: 'Plugins',
items: [{ type: 'autogenerated', dirName: 'docs/plugins' }],
},
],
},

{
3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -184,5 +184,6 @@
"prettier --write"
],
"**/*.{ts, tsx, json}": "eslint --fix"
}
},
"packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
}

0 comments on commit 008904a

Please sign in to comment.