docs: finalized all content for the docs

zamanapp · Oct 6, 2023 · 5e6d8d1 · 5e6d8d1
1 parent 9204397
commit 5e6d8d1
Show file tree

Hide file tree

Showing 8 changed files with 190 additions and 12 deletions.
diff --git a/docs/.vitepress/cache/deps/_metadata.json b/docs/.vitepress/cache/deps/_metadata.json
@@ -1,35 +1,35 @@
 {
-  "hash": "69e45955",
-  "browserHash": "b6732085",
+  "hash": "2ac064c2",
+  "browserHash": "17e02623",
   "optimized": {
     "vue": {
       "src": "../../../../node_modules/.pnpm/[email protected]/node_modules/vue/dist/vue.runtime.esm-bundler.js",
       "file": "vue.js",
-      "fileHash": "d40eabbe",
+      "fileHash": "28607c0c",
       "needsInterop": false
     },
     "vitepress > @vue/devtools-api": {
       "src": "../../../../node_modules/.pnpm/@[email protected]/node_modules/@vue/devtools-api/lib/esm/index.js",
       "file": "vitepress___@vue_devtools-api.js",
-      "fileHash": "df4eb89c",
+      "fileHash": "a477b2a0",
       "needsInterop": false
     },
     "vitepress > @vueuse/integrations/useFocusTrap": {
       "src": "../../../../node_modules/.pnpm/@[email protected][email protected][email protected]/node_modules/@vueuse/integrations/useFocusTrap.mjs",
       "file": "vitepress___@vueuse_integrations_useFocusTrap.js",
-      "fileHash": "037c02d1",
+      "fileHash": "f7bf987a",
       "needsInterop": false
     },
     "vitepress > mark.js/src/vanilla.js": {
       "src": "../../../../node_modules/.pnpm/[email protected]/node_modules/mark.js/src/vanilla.js",
       "file": "vitepress___mark__js_src_vanilla__js.js",
-      "fileHash": "3355a13b",
+      "fileHash": "00fa4d89",
       "needsInterop": false
     },
     "vitepress > minisearch": {
       "src": "../../../../node_modules/.pnpm/[email protected]/node_modules/minisearch/dist/es/index.js",
       "file": "vitepress___minisearch.js",
-      "fileHash": "ab03ccc7",
+      "fileHash": "e45c5000",
       "needsInterop": false
     }
   },

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -1,5 +1,7 @@
 import { defineConfig } from 'vitepress'
 import { version } from '../../package.json'
+import footnote from 'markdown-it-footnote'
+import taskList from 'markdown-it-task-lists'
 
 // if version doesn't work we need to use this plugin https://github.com/semantic-release/git
 export default defineConfig({
@@ -37,6 +39,10 @@ export default defineConfig({
       light: 'light-plus',
       dark: 'one-dark-pro',
     },
+    config(md) {
+      md.use(footnote)
+      md.use(taskList)
+    },
   },
 })
 
@@ -121,5 +127,10 @@ function sidebarGuide() {
       collapsible: true,
       items: [{ text: 'API Reference', link: '/api' }],
     },
+    {
+      text: 'Roadmap',
+      collapsible: true,
+      items: [{ text: 'The future', link: '/roadmap' }],
+    },
   ]
 }
diff --git a/docs/config/methods.md b/docs/config/methods.md
@@ -1,3 +1,115 @@
 # Calculation Methods
 
-WIP
+## Overview
+
+Calculation methods are sets of parameters and rules used to compute Islamic prayer times. These methods are often standardized by religious authorities or geographical regions. They define specific angles of the sun or time intervals, and other factors to accurately calculate the times for Fajr, Sunrise, Dhuhr, Asr, Maghrib, and Isha prayers.
+
+## Available Methods and Their Parameters
+
+We recommend using `prayers-call` pre-defined calculation methods, as they are endorsed by official religious authorities making them more accurate and consistent with the local community. These methods are available via the [`Method`](../api.md#method) enum. However, if you need to, you can create your own custom method using the [`CustomMethod`](../api.md#custommethod) interface for that check the [Building a Custom Method](#building-a-custom-method) section.
+
+| Method Name            | Fajr Angle | Isha Angle | Isha Interval | Method Adjustments                            |
+| ---------------------- | ---------- | ---------- | ------------- | --------------------------------------------- |
+| UMM_AL_QURA            | 18.5       | 0          | 90[^1]        | None                                          |
+| MUSLIM_WORLD_LEAGUE    | 18         | 17         | 0             | `{ dhuhr: 1 }`                                |
+| MOONSIGHTING_COMMITTEE | 18         | 18         | 0             | `{dhuhr: 5, maghrib: 3}`                      |
+| KUWAIT                 | 18         | 17.5       | 0             | None                                          |
+| QATAR                  | 18         | 0          | 90            | None                                          |
+| EGYPTIAN               | 19.5       | 17.5       | 0             | `{dhuhr: 1}`                                  |
+| KARACHI                | 18         | 18         | 0             | `{dhuhr: 1}`                                  |
+| DUBAI                  | 18.2       | 18.2       | 0             | `{sunrise: -3, dhuhr: 3, asr: 3, maghrib: 3}` |
+| SINGAPORE              | 20         | 18         | 0             | `{dhuhr: 1}`                                  |
+| NORTH_AMERICA          | 15         | 15         | 0             | `{dhuhr: 1}`                                  |
+| TURKEY                 | 18         | 17         | 0             | `{sunrise: -7, dhuhr: 5, asr: 4, maghrib: 7}` |
+| JORDAN                 | 18         | 18         | 0             | None                                          |
+| LIBYA                  | 18         | 18         | 0             | None                                          |
+| PALESTINE              | 18         | 18         | 0             | None                                          |
+| SUDAN                  | 18         | 18         | 0             | None                                          |
+| ALGERIA                | 18         | 17         | 0             | `{maghrib: 3}`                                |
+| BAHRAIN                | 18         | 0          | 90            | None                                          |
+| BRUNEI                 | 20         | 18         | 0             | `{dhuhr: 1}`                                  |
+| INDONESIA              | 20         | 18         | 0             | `{dhuhr: 1}`                                  |
+| MALAYSIA               | 20         | 18         | 0             | `{dhuhr: 1}`                                  |
+| FRANCE                 | 12         | 12         | 0             | None                                          |
+| GERMANY                | 18         | 16.5       | 0             | None                                          |
+| IRAQ                   | 19.5       | 17.5       | 0             | `{dhuhr: 7, asr: 7, maghrib: 4}`              |
+| MOROCCO                | 19         | 17         | 0             | `{dhuhr: 5, maghrib: 2}`                      |
+| RUSSIA                 | 16         | 15         | 0             | None                                          |
+| OMAN                   | 18         | 18         | 0             | `{dhuhr: 5, asr: 5, maghrib: 5}`              |
+| SYRIA                  | 18.5       | 17.5       | 0             | `{sunrise: -7, dhuhr: 5, asr: 3, maghrib: 7}` |
+| TUNISIA                | 18         | 18         | 0             | `{dhuhr: 7, maghrib: 2}`                      |
+| YEMEN                  | 18         | 17         | 0             | `{dhuhr: 2}`                                  |
+| STANDARD               | 18         | 18         | 0             | None                                          |
+
+[^1]: Umm Al Qura method changes the isha interval to 120 minutes instead of 90 minutes (+30 minutes) during Ramadan. `prayers-call` automatically handles this change for you.
+
+::: tip
+There are other calculation parameters to take in consideration that also varies from one method to another or from one country/region to another. Example of that would be the [`AsrTime`](./config.md#asrtime), [`HighLatitudeRule`](./config.md#highlatituderule), [`adjustForRamadan`](./config.md#adjustforramadan) and [`PolarCircleResolution`](./config.md#polarcircleresolution)
+:::
+
+::: tip Help wanted
+We're looking for help to add more calculation methods to `prayers-call`. If you have the knowledge and resources to help us or have found any issue, please [open an issue](https://github.com/whiterocktech/prayers-call/issues/new/choose) or submit a pull request.
+:::
+
+::: warning Disclaimer
+The calculation methods provided are based on our best capacity of research and publicly available information. Some of them might not be accurate or up to date. We welcome contributions from the community to improve and expand this data.
+:::
+
+## Using the `recommendMethod` Helper Function
+
+`prayers-call` offers the [`recommendMethod`](../api.md#functions) helper function, designed to suggest the most appropriate calculation methods for prayer times based on the country of a given location. The function accepts a [`CoordinatesObject`](../api.md#coordinatesobject) returns an array of recommended methods, ranked by best guess or by the number of methods commonly used in that specific country. If no match is found, the function returns `undefined`. Here's an example:"
+
+```ts
+import { recommendMethod } from 'prayers-call'
+
+const methods = recommendMethod({ latitude: 21.3891, longitude: 39.8579 }) // mekka coordinates
+console.log(methods) // Output: ['UmmAlQura']
+```
+
+::: tip Help wanted
+We're looking for help to map more countries with their respective methods. If you have the knowledge and resources to help us or have found any issue, please [open an issue](https://github.com/whiterocktech/prayers-call/issues/new/choose) or submit a pull request.
+:::
+
+::: warning Disclaimer
+The mapping provided are based on our best capacity of research and publicly available information. Some of the results might not be accurate or up to date. We welcome contributions from the community to improve and expand this data.
+:::
+
+## Building a Custom Method
+
+It is possible to use a custom calculation method by passing a [`CustomMethod`](../api.md#custommethod) object to the `method` property on the [`CalculationsConfig`](../api.md#calculationsconfig) or the [`ReactiveCalculationsConfig`](../api.md#reactivecalculationsconfig).
+
+The following parameters are available:
+
+- **`fajrAngle`**: The angle of the sun, in degrees, used to calculate Fajr time. Default is 18 degrees.
+- **`ishaAngle`**: The angle of the sun, in degrees, used to calculate Isha time. Default is 18 degrees.
+- **`ishaInterval`**: The number of minutes after Maghrib for Isha. If set, `ishaAngle` is ignored. Default is 0 minutes.
+- **`maghribAngle`**: The angle of the sun, in degrees, used to calculate Maghrib. This is specifically used by the Tehran method. Default is 0 degrees.
+- **`methodAdjustments`**: Custom adjustments, in minutes, for each prayer time. Default adjustments are all zero.
+
+### Example usage
+
+```ts
+const MyCustomMethod: CustomMethod = {
+  fajrAngle: 17,
+  ishaAngle: 18,
+  methodAdjustments: { fajr: 2, isha: 2 },
+}
+
+const calculator = new StaticCalculator({
+  date: new Date(2022, 1, 1),
+  latitude: 2.9213,
+  longitude: 101.6559,
+  method: MyCustomMethod,
+  adjustments: { dhuhr: 3, asr: 3, isha: 2 },
+})
+```
+
+## Community Note
+
+This documentation and the methods provided are based on our best capacity of research and publicly available information. We welcome contributions from the community to improve and expand this data.
+
+## Future Plans
+
+We're working on releasing an open-source tool that allows you to test, compare, and build calculation methods. Check our [roadmap](../roadmap.md) and stay tuned for updates.
+
+Feel free to contribute and help us make this resource even better.
diff --git a/docs/guide/introduction.md b/docs/guide/introduction.md
@@ -2,7 +2,9 @@
 
 ## What Is It?
 
-`prayers-call` is a TypeScript library designed for calculating Islamic prayer times. It can be used in both Node.js and browser environments. Built on top of [adhan-js](https://github.com/batoulapps/adhan-js), the library aims for accuracy, versatility, and ease of use.
+`prayers-call` is a TypeScript library designed for calculating Islamic prayer times. It can be used in both Node.js and browser environments. Currently[^1] built on top of [adhan-js](https://github.com/batoulapps/adhan-js), the library aims for accuracy, versatility, and ease of use.
+
+[^1]: We're planning a new version that is built from scratch to offer more features with a native reactivity system. Check our [roadmap](../roadmap.md) and stay tuned for updates.
 
 ## Why This Library?
 

diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -1,10 +1,38 @@
+<!-- - Prepare a repository for common files like contributing, code of conduct, license, etc. -->
+
+# Roadmap
+
+This roadmap outlines our future plans and the features we're considering. We welcome contributions and feedback from the community.
+
+## In Progress
+
+- [ ] Write more tests to cover the library
+- [ ] Improve the docs to have examples imported from actual TS files
+- [x] ~~Include Algolia search in the docs~~ (done via [minisearch](https://github.com/lucaong/minisearch/))
+
+## Planned
+
+- Offer open-source tools for comparing and building calculation methods
+- Translate the docs to Arabic <Badge type="tip" text="Help Needed" />
+- Re-write the library from scratch, making it reactive from the ground up [(using Vue 3 reactivity package from the core API)](https://github.com/vuejs/core/tree/main/packages/reactivity) <Badge type="tip" text="^2.0.0" />
+- Add altitude to the calculation formula <Badge type="tip" text="^2.0.0" />
+- Add support for `Temporal` <Badge type="tip" text="^2.0.0" />
+- Offer testing utilities for reactive code
+
+## Under Consideration
+
+- Do we need to have daylight saving times handled in the library? If yes, what's the best way to do it?
+
+## How to Contribute
+
+We're always open to contributions and suggestions. If you have ideas or find issues, please [open an issue](https://github.com/your-repo/issues/new/choose) or submit a pull request.
+
 - Write more tests to cover the library
 - Offer open source tools to make comparing and building calculation methods easier.
-- Re-write the library from scratch making it reactive from the ground up (using vue 3 reactive core api)
+- Re-write the library from scratch making it reactive from the ground up [(using vue 3 reactivity package from the core api)](https://github.com/vuejs/core/tree/main/packages/reactivity)
 - Do we need to have daylight saving times handled in the library? if yes what's the best way to do it?
 - improve the docs to have examples imported from actual ts files <!-- https://vitepress.dev/guide/markdown#import-code-snippets -->
 - translated the docs to Arabic
 - Add altitude to the calculation formula
 - Support `Temporal` instead of `Date`
 - Offer testing utilities for reactive code
-- include Algolia search in the docs
diff --git a/examples/index.ts b/examples/index.ts
@@ -1,5 +1,13 @@
 import { Methods } from '../src/types/Methods'
-import { Formatter, HighLatitudeRule, HijriCalendar, PrayerNames, ReactiveCalculator, StaticCalculator } from '../src'
+import {
+  Formatter,
+  HighLatitudeRule,
+  HijriCalendar,
+  PrayerNames,
+  ReactiveCalculator,
+  StaticCalculator,
+  recommendMethod,
+} from '../src'
 import type { TimeEventObject } from '../src'
 import { TimesNames } from '../src/types/TimeObject'
 
@@ -27,6 +35,9 @@ console.log('default formatter', formatterExample.formatDate(date))
 
 const rule = HighLatitudeRule.recommended({ latitude: 59.91, longitude: 10.75 }) // SeventhOfTheNight
 console.log(rule)
+
+const methods = recommendMethod({ latitude: 21.3891, longitude: 39.8579 })
+console.log(methods) // Output: ['UMM_AL_QURA']
 // console.log(calculator.getPrayerTime(PrayerNames.FAJR))
 // console.log('Middle', calculator.getMiddleOfTheNightTime().time?.toLocaleString())
 // console.log('LastThird', calculator.getLastThirdOfTheNightTime().time?.toLocaleString())

diff --git a/package.json b/package.json
@@ -70,6 +70,8 @@
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-tsdoc": "^0.2.17",
     "esno": "^0.16.3",
+    "markdown-it-footnote": "^3.0.3",
+    "markdown-it-task-lists": "^2.1.1",
     "pnpm": "^7.9.0",
     "prettier": "^2.7.1",
     "rimraf": "^3.0.2",

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml