Skip to content

Commit 348fd83

Browse files
ciatphciatph
committed
docs: use details/summary
1 parent 551318a commit 348fd83

File tree

1 file changed

+143
-29
lines changed

1 file changed

+143
-29
lines changed

‎README.md

Lines changed: 143 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -65,30 +65,41 @@ The following dependencies are used for this project. Feel free to use other dep
6565

6666
</details>
6767

68-
## Contents
68+
## Table of Contents
69+
70+
<details>
71+
<summary>
72+
Click to expand the table of contents
73+
</summary>
74+
6975

7076
- [ph-municipalities](#ph-municipalities)
7177
- [Class Documentation](#class-documentation)
7278
- [Requirements](#requirements)
73-
- [Contents](#contents)
79+
- [Table of Contents](#table-of-contents)
7480
- [Installation](#installation)
7581
- [Installation Using Docker](#installation-using-docker)
7682
- [Available Scripts](#available-scripts)
77-
- [`npm start` / `npm run list:region`](#npm-start--npm-run-listregion)
78-
- [`npm run list:province`](#npm-run-listprovince)
79-
- [`npm run example`](#npm-run-example)
80-
- [`npm run generate-docs`](#npm-run-generate-docs)
81-
- [`npm run docs:install`](#npm-run-docsinstall)
82-
- [`npm run docs:build`](#npm-run-docsbuild)
83-
- [`build:win:region`](#buildwinregion)
84-
- [`build:win:province`](#buildwinprovince)
85-
- [`build:win:all`](#buildwinall)
86-
- [`npm run minify:region`](#npm-run-minifyregion)
87-
- [`npm run minify:province`](#npm-run-minifyprovince)
88-
- [`npm run minify:all`](#npm-run-minifyall)
89-
- [`npm run lint`](#npm-run-lint)
90-
- [`npm run lint:fix`](#npm-run-lintfix)
91-
- [`npm test`](#npm-test)
83+
- [Interactive CLI Scripts](#interactive-cli-scripts)
84+
- [`npm start` / `npm run list:region`](#npm-start--npm-run-listregion)
85+
- [`npm run list:province`](#npm-run-listprovince)
86+
- [NPM Scripts for Building Documentation](#npm-scripts-for-building-documentation)
87+
- [`npm run generate-docs`](#npm-run-generate-docs)
88+
- [`npm run docs:install`](#npm-run-docsinstall)
89+
- [`npm run docs:build`](#npm-run-docsbuild)
90+
- [NPM Scripts for Building Windows Executable Files of the Interactive CLI Scripts](#npm-scripts-for-building-windows-executable-files-of-the-interactive-cli-scripts)
91+
- [`build:win:region`](#buildwinregion)
92+
- [`build:win:province`](#buildwinprovince)
93+
- [`build:win:all`](#buildwinall)
94+
- [`npm run minify:region`](#npm-run-minifyregion)
95+
- [NPM Scripts for Compiling the Interactive CLI Scripts into Stand-Alone Scripts](#npm-scripts-for-compiling-the-interactive-cli-scripts-into-stand-alone-scripts)
96+
- [`npm run minify:province`](#npm-run-minifyprovince)
97+
- [`npm run minify:all`](#npm-run-minifyall)
98+
- [NPM Scripts for Linting Files and Unit Testing](#npm-scripts-for-linting-files-and-unit-testing)
99+
- [`npm run lint`](#npm-run-lint)
100+
- [`npm run lint:fix`](#npm-run-lintfix)
101+
- [`npm test`](#npm-test)
102+
- [`npm run example`](#npm-run-example)
92103
- [Class Usage](#class-usage)
93104
- [Load and Parse a Local Excel File](#load-and-parse-a-local-excel-file)
94105
- [Download and Parse a Remote Excel File](#download-and-parse-a-remote-excel-file)
@@ -101,6 +112,8 @@ The following dependencies are used for this project. Feel free to use other dep
101112
- [Using NodeJS](#using-nodejs)
102113
- [Troubleshooting](#troubleshooting)
103114

115+
</details>
116+
104117
## Installation
105118

106119
1. Clone this repository.<br>
@@ -114,6 +127,9 @@ The following dependencies are used for this project. Feel free to use other dep
114127

115128
3. Create a `.env` file from the `.env.example` file inside the `/app` directory. Use the default values for the following environment variables.
116129

130+
<details>
131+
<summary>List of .env variables and their description.</summary>
132+
117133
> **INFO:** If installed as an NPM package with `npm i ph-municipalities`, create the `.env` file inside the NPM project's root directory.
118134
119135
| Variable Name | Description |
@@ -124,13 +140,18 @@ The following dependencies are used for this project. Feel free to use other dep
124140
| SPECIAL_CHARACTERS | Key-value pairs of special characters or garbled text and their normalized text conversions, delimited by the `":"` character.<br>Multiple key-value pairs are delimited by the `","` character.<br>If a special character key's value is a an empty string, write it as i.e.,: `"some-garbled-text:"` |
125141
| IMAGE_URL | Raw URL of the README image file from this GitHub repository.<br> <blockquote>**NOTE:** Only add this variable in the GitHub Secrets for publishing to the NPM registry since NPM does not allow displaying images by relative path.</blockquote> |
126142

143+
</details>
144+
127145
## Installation Using Docker
128146

129147
We can use Docker to run dockerized Node app for local development mode. The following methods require Docker and Docker compose correctly installed and set up on your development machine.
130148

131149
### Docker Dependencies
132150

151+
<details>
152+
<summary>
133153
The following dependencies are used to build and run the image. Please feel feel free to use other OS and versions as needed.
154+
</summary>
134155

135156
1. Ubuntu 22.04.1
136157
- Docker version 23.0.1, build a5eeb1
@@ -141,8 +162,13 @@ The following dependencies are used to build and run the image. Please feel feel
141162
- Docker Compose version v2.27.1-desktop.1
142163
- Docker Engine version 26.1.4, build 5650f9b
143164

165+
</details>
166+
144167
### Docker for Localhost Development
145168

169+
<details>
170+
<summary>Steps for using Docker with local development</summary>
171+
146172
1. Set up the environment variables for the `/app` directory. Visit the [Installation](#installation) section, **step #3** for more information.
147173

148174
2. Stop and delete all docker instances for a fresh start.
@@ -167,6 +193,8 @@ The following dependencies are used to build and run the image. Please feel feel
167193
- For new scripts (example only):<br>
168194
`docker exec -it ph-municipalities node ./src/new.js`
169195
196+
</details>
197+
170198
## Available Scripts
171199
172200
> _**Note:** These NPM scripts run relative within the `/app` directory, when working on a git-cloned repository of the app. To run using only NodeJS, navigate first to the `/app` directory and execute a target script, for example:_
@@ -176,6 +204,11 @@ cd app
176204
npm run list:region
177205
```
178206
207+
<details>
208+
<summary style="font-size: 18px;" id="interactive-cli-scripts">
209+
<b>Interactive CLI Scripts</b>
210+
</summary>
211+
179212
### `npm start` / `npm run list:region`
180213
181214
- Asks users to enter the download URL of a remote excel file or use the default local excel file
@@ -197,13 +230,15 @@ npm run list:region
197230
- Run the script as follows if installed using `npm i ph-municipalities`:
198231
- `node .\node_modules\ph-municipalities\src\scripts\by_province.js`
199232
200-
### `npm run example`
201-
202-
- Downloads and parses a remote excel file.
203-
- Demonstrates sample usage with `await`
233+
</details>
204234
205235
---
206236
237+
<details>
238+
<summary style="font-size: 18px;" id="npm-scripts-for-building-documentation">
239+
<b>NPM Scripts for Building Documentation</b>
240+
</summary>
241+
207242
### `npm run generate-docs`
208243
209244
Builds the class documentation into the **/docs** directory.
@@ -244,8 +279,15 @@ docker exec -u root -it ph-municipalities npm run docs:install
244279
docker exec -u root -it ph-municipalities npm run docs:build
245280
```
246281

282+
</details>
283+
247284
---
248285

286+
<details>
287+
<summary style="font-size: 18px;" id="npm-scripts-for-building-windows-executable-files-of-the-interactive-cli-scripts">
288+
<b>NPM Scripts for Building Windows Executable Files of the Interactive CLI Scripts</b>
289+
</summary>
290+
249291
### `build:win:region`
250292

251293
- Package the Node.js project's `npm start` script into a stand-alone windows `node16-win-x64` executable.
@@ -261,8 +303,15 @@ docker exec -u root -it ph-municipalities npm run docs:build
261303
- Package the Node.js project's `npm start` and `npm list:province` script into a stand-alone windows `node16-win-x64` executables in one go.
262304
- Each window executable file will be stored in the `/dist` directory.
263305

306+
</details>
307+
264308
---
265309

310+
<details>
311+
<summary style="font-size: 18px;" id="npm-scripts-for-compiling-the-interactive-cli-scripts-into-stand-alone-scripts">
312+
<b>NPM Scripts for Compiling the Interactive CLI Scripts into Stand-Alone Scripts</b>
313+
</summary>
314+
266315
### `npm run minify:region`
267316

268317
- Compiles the Node.js project's `npm list:region` script and dependencies into a single script using [**ncc**](https://www.npmjs.com/package/@vercel/ncc).
@@ -280,8 +329,15 @@ docker exec -u root -it ph-municipalities npm run docs:build
280329
- Run the `npm list:region` and `npm list:province` scripts in one go.
281330
- Each compiled/minified files will be stored in the `/dist` directory.
282331

332+
</details>
333+
283334
---
284335

336+
<details>
337+
<summary style="font-size: 18px;" id="npm-scripts-for-linting-files-and-unit-testing">
338+
<b>NPM Scripts for Linting Files and Unit Testing</b>
339+
</summary>
340+
285341
### `npm run lint`
286342

287343
Lint JavaScript source codes.
@@ -294,6 +350,13 @@ Fix JavaScript lint errors.
294350

295351
Run tests defined in the `/app/__tests__` directory.
296352

353+
### `npm run example`
354+
355+
- Downloads and parses a remote excel file.
356+
- Demonstrates sample usage with `await`
357+
358+
</details>
359+
297360
## Class Usage
298361

299362
Below are example usages of the `ExcelFile` class, run from the **/app/src/examples** directory. Check out the `/app/src/examples/sample_usage.js` file for more examples.
@@ -302,7 +365,9 @@ Below are example usages of the `ExcelFile` class, run from the **/app/src/examp
302365

303366
This is a simple usage example of the `ExcelFile` class.
304367

305-
**Simple Usage**
368+
<details>
369+
<summary><b>Simple Usage</b></summary>
370+
306371
```javascript
307372
const path = require('path')
308373
const ExcelFile = require('../classes/excel')
@@ -346,7 +411,13 @@ file.datalist = [
346411
{ municipality: 'Bucay', province: 'Abra' }]
347412
```
348413

349-
**Reading regions, provinces and municipalities**
414+
</details>
415+
416+
<details>
417+
<summary>
418+
<b>Reading regions, provinces and municipalities</b>
419+
</summary>
420+
350421
```javascript
351422
const path = require('path')
352423
const ExcelFile = require('../classes/excel')
@@ -377,10 +448,17 @@ const municipalitiesFromProvince = file.listMunicipalities({ provinces })
377448
console.log(`---municipalities`, municipalitiesFromProvince)
378449
```
379450

451+
</details>
452+
380453
### Download and Parse a Remote Excel File
381454

382455
Adding a `url` field in the constructor parameter prepares the class to download a remote Excel file for the data source.
383456

457+
<details>
458+
<summary>
459+
<b>Remote Excel file download example</b>
460+
</summary>
461+
384462
> **INFO:** Run the `.init()` method after initializing a class with a `url` parameter to start the async file download.
385463
386464
```javascript
@@ -410,9 +488,14 @@ const main = async () => {
410488
main()
411489
```
412490

491+
</details>
492+
413493
### Alternate Usage - Events
414494

415-
Initialize an `ExcelFile` class instance.
495+
<details>
496+
<summary>
497+
<b>Initialize an ExcelFile class instance.</b>
498+
</summary>
416499

417500
```javascript
418501
require('dotenv').config()
@@ -446,6 +529,8 @@ const main = () => {
446529
main()
447530
```
448531

532+
</details>
533+
449534
### Using a Custom Configuration File
450535

451536
The **ph-municipalities** `ExcelFile` and `ExcelFactory` classes use a default configuration file to define their regions and provinces in the `/app/config/regions.json` file. The regions and provinces data in this file syncs with the PAGASA Seasonal and 10-Day Weather Forecast Excel files provinces and municipalities naming convention, encoded by hand as of August 24, 2024.
@@ -454,7 +539,11 @@ Follow the codes to define a custom regions config file, following the format of
454539

455540
> _**Note:** The custom config file's province/municipality names should match those in the 10-day Excel file._
456541
457-
**config.json**
542+
<details>
543+
<summary>
544+
<b>config.json</b>
545+
</summary>
546+
458547
```
459548
{
460549
"metadata": {
@@ -485,7 +574,13 @@ Follow the codes to define a custom regions config file, following the format of
485574
}
486575
```
487576

488-
**Custom config usage**
577+
</details>
578+
579+
<details>
580+
<summary>
581+
<b>Custom config usage</b>
582+
</summary>
583+
489584
```javascript
490585
require('dotenv').config()
491586
const path = require('path')
@@ -518,6 +613,8 @@ console.log('\nProvince/municipality names should match with those in the 10-day
518613
console.log('---municipalities', municipalities)
519614
```
520615

616+
</details>
617+
521618
## Building Standalone Windows Executables
522619

523620
The main npm scripts can be packaged into standalone windows executables. Pre-compiled windows binaries are available for download in the latest [Releases](https://github.com/ciatph/ph-municipalities/releases) download page.
@@ -550,7 +647,10 @@ The main npm scripts can be compiled into standalone JavaScript files together w
550647

551648
The class documentation uses [JSDoc](https://jsdoc.app/) annotations where applicable in the JavaScript source codes inside the **/src** directory. There are two (2) options for building the class documentation.
552649

553-
### Using Docker
650+
<details>
651+
<summary style="font-size: 18px;" id="using-docker">
652+
<b>Using Docker</b>
653+
</summary>
554654

555655
1. Run docker for localhost development. Refer to the [Docker for Localhost Development](#docker-for-localhost-development) section for more information.
556656

@@ -564,7 +664,14 @@ The class documentation uses [JSDoc](https://jsdoc.app/) annotations where appli
564664
docker exec -u root -it ph-municipalities npm run docs:build
565665
```
566666

567-
### Using NodeJS
667+
</details>
668+
669+
<br>
670+
671+
<details>
672+
<summary style="font-size: 18px;" id="using-nodejs">
673+
<b>Using NodeJS</b>
674+
</summary>
568675

569676
1. Install the dependencies for JSDoc. Refer to the [**`npm run generate-docs`**](#npm-run-generate-docs) Script usage for more information.
570677
2. Copy Bash scripts to the **/app** directory.
@@ -587,11 +694,16 @@ The class documentation uses [JSDoc](https://jsdoc.app/) annotations where appli
587694
./scripts/docs-build.sh
588695
```
589696

697+
</details>
698+
590699
## Troubleshooting
591700

592701
This section describes several common errors and related fixes.
593702

594-
### EACCESS: permission denied
703+
<details>
704+
<summary style="font-size: 18px;">
705+
<b>EACCESS: permission denied</b>
706+
</summary>
595707

596708
#### Information
597709

@@ -607,7 +719,9 @@ This section describes several common errors and related fixes.
607719
`sudo chown -R <APP_UID>:<APP_UID> ./app`
608720
3. Re-run the NPM script.
609721

722+
</details>
610723

724+
<br>
611725

612726
@ciatph<br>
613727
20220807

0 commit comments

Comments
 (0)