From 348fd830eda8ad8adc2ffa4181f78a85bad39a36 Mon Sep 17 00:00:00 2001 From: ciatph Date: Fri, 13 Sep 2024 01:14:10 +0800 Subject: [PATCH] docs: use details/summary --- README.md | 172 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 143 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 7961231..f7a1562 100644 --- a/README.md +++ b/README.md @@ -65,30 +65,41 @@ The following dependencies are used for this project. Feel free to use other dep -## Contents +## Table of Contents + +
+ +Click to expand the table of contents + + - [ph-municipalities](#ph-municipalities) - [Class Documentation](#class-documentation) - [Requirements](#requirements) -- [Contents](#contents) +- [Table of Contents](#table-of-contents) - [Installation](#installation) - [Installation Using Docker](#installation-using-docker) - [Available Scripts](#available-scripts) - - [`npm start` / `npm run list:region`](#npm-start--npm-run-listregion) - - [`npm run list:province`](#npm-run-listprovince) - - [`npm run example`](#npm-run-example) - - [`npm run generate-docs`](#npm-run-generate-docs) - - [`npm run docs:install`](#npm-run-docsinstall) - - [`npm run docs:build`](#npm-run-docsbuild) - - [`build:win:region`](#buildwinregion) - - [`build:win:province`](#buildwinprovince) - - [`build:win:all`](#buildwinall) - - [`npm run minify:region`](#npm-run-minifyregion) - - [`npm run minify:province`](#npm-run-minifyprovince) - - [`npm run minify:all`](#npm-run-minifyall) - - [`npm run lint`](#npm-run-lint) - - [`npm run lint:fix`](#npm-run-lintfix) - - [`npm test`](#npm-test) + - [Interactive CLI Scripts](#interactive-cli-scripts) + - [`npm start` / `npm run list:region`](#npm-start--npm-run-listregion) + - [`npm run list:province`](#npm-run-listprovince) + - [NPM Scripts for Building Documentation](#npm-scripts-for-building-documentation) + - [`npm run generate-docs`](#npm-run-generate-docs) + - [`npm run docs:install`](#npm-run-docsinstall) + - [`npm run docs:build`](#npm-run-docsbuild) + - [NPM Scripts for Building Windows Executable Files of the Interactive CLI Scripts](#npm-scripts-for-building-windows-executable-files-of-the-interactive-cli-scripts) + - [`build:win:region`](#buildwinregion) + - [`build:win:province`](#buildwinprovince) + - [`build:win:all`](#buildwinall) + - [`npm run minify:region`](#npm-run-minifyregion) + - [NPM Scripts for Compiling the Interactive CLI Scripts into Stand-Alone Scripts](#npm-scripts-for-compiling-the-interactive-cli-scripts-into-stand-alone-scripts) + - [`npm run minify:province`](#npm-run-minifyprovince) + - [`npm run minify:all`](#npm-run-minifyall) + - [NPM Scripts for Linting Files and Unit Testing](#npm-scripts-for-linting-files-and-unit-testing) + - [`npm run lint`](#npm-run-lint) + - [`npm run lint:fix`](#npm-run-lintfix) + - [`npm test`](#npm-test) + - [`npm run example`](#npm-run-example) - [Class Usage](#class-usage) - [Load and Parse a Local Excel File](#load-and-parse-a-local-excel-file) - [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 - [Using NodeJS](#using-nodejs) - [Troubleshooting](#troubleshooting) +
+ ## Installation 1. Clone this repository.
@@ -114,6 +127,9 @@ The following dependencies are used for this project. Feel free to use other dep 3. Create a `.env` file from the `.env.example` file inside the `/app` directory. Use the default values for the following environment variables. +
+ List of .env variables and their description. + > **INFO:** If installed as an NPM package with `npm i ph-municipalities`, create the `.env` file inside the NPM project's root directory. | Variable Name | Description | @@ -124,13 +140,18 @@ The following dependencies are used for this project. Feel free to use other dep | SPECIAL_CHARACTERS | Key-value pairs of special characters or garbled text and their normalized text conversions, delimited by the `":"` character.
Multiple key-value pairs are delimited by the `","` character.
If a special character key's value is a an empty string, write it as i.e.,: `"some-garbled-text:"` | | IMAGE_URL | Raw URL of the README image file from this GitHub repository.
**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.
| +
+ ## Installation Using Docker 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. ### Docker Dependencies +
+ The following dependencies are used to build and run the image. Please feel feel free to use other OS and versions as needed. + 1. Ubuntu 22.04.1 - 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 - Docker Compose version v2.27.1-desktop.1 - Docker Engine version 26.1.4, build 5650f9b +
+ ### Docker for Localhost Development +
+Steps for using Docker with local development + 1. Set up the environment variables for the `/app` directory. Visit the [Installation](#installation) section, **step #3** for more information. 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 - For new scripts (example only):
`docker exec -it ph-municipalities node ./src/new.js` +
+ ## Available Scripts > _**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 npm run list:region ``` +
+ + Interactive CLI Scripts + + ### `npm start` / `npm run list:region` - 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 - Run the script as follows if installed using `npm i ph-municipalities`: - `node .\node_modules\ph-municipalities\src\scripts\by_province.js` -### `npm run example` - -- Downloads and parses a remote excel file. -- Demonstrates sample usage with `await` +
--- +
+ + NPM Scripts for Building Documentation + + ### `npm run generate-docs` Builds the class documentation into the **/docs** directory. @@ -244,8 +279,15 @@ docker exec -u root -it ph-municipalities npm run docs:install docker exec -u root -it ph-municipalities npm run docs:build ``` +
+ --- +
+ + NPM Scripts for Building Windows Executable Files of the Interactive CLI Scripts + + ### `build:win:region` - 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 - 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. - Each window executable file will be stored in the `/dist` directory. +
+ --- +
+ + NPM Scripts for Compiling the Interactive CLI Scripts into Stand-Alone Scripts + + ### `npm run minify:region` - 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 - Run the `npm list:region` and `npm list:province` scripts in one go. - Each compiled/minified files will be stored in the `/dist` directory. +
+ --- +
+ + NPM Scripts for Linting Files and Unit Testing + + ### `npm run lint` Lint JavaScript source codes. @@ -294,6 +350,13 @@ Fix JavaScript lint errors. Run tests defined in the `/app/__tests__` directory. +### `npm run example` + +- Downloads and parses a remote excel file. +- Demonstrates sample usage with `await` + +
+ ## Class Usage 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 This is a simple usage example of the `ExcelFile` class. -**Simple Usage** +
+Simple Usage + ```javascript const path = require('path') const ExcelFile = require('../classes/excel') @@ -346,7 +411,13 @@ file.datalist = [ { municipality: 'Bucay', province: 'Abra' }] ``` -**Reading regions, provinces and municipalities** +
+ +
+ + Reading regions, provinces and municipalities + + ```javascript const path = require('path') const ExcelFile = require('../classes/excel') @@ -377,10 +448,17 @@ const municipalitiesFromProvince = file.listMunicipalities({ provinces }) console.log(`---municipalities`, municipalitiesFromProvince) ``` +
+ ### Download and Parse a Remote Excel File Adding a `url` field in the constructor parameter prepares the class to download a remote Excel file for the data source. +
+ + Remote Excel file download example + + > **INFO:** Run the `.init()` method after initializing a class with a `url` parameter to start the async file download. ```javascript @@ -410,9 +488,14 @@ const main = async () => { main() ``` +
+ ### Alternate Usage - Events -Initialize an `ExcelFile` class instance. +
+ + Initialize an ExcelFile class instance. + ```javascript require('dotenv').config() @@ -446,6 +529,8 @@ const main = () => { main() ``` +
+ ### Using a Custom Configuration File 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 > _**Note:** The custom config file's province/municipality names should match those in the 10-day Excel file._ -**config.json** +
+ + config.json + + ``` { "metadata": { @@ -485,7 +574,13 @@ Follow the codes to define a custom regions config file, following the format of } ``` -**Custom config usage** +
+ +
+ + Custom config usage + + ```javascript require('dotenv').config() const path = require('path') @@ -518,6 +613,8 @@ console.log('\nProvince/municipality names should match with those in the 10-day console.log('---municipalities', municipalities) ``` +
+ ## Building Standalone Windows Executables 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 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. -### Using Docker +
+ + Using Docker + 1. Run docker for localhost development. Refer to the [Docker for Localhost Development](#docker-for-localhost-development) section for more information. @@ -564,7 +664,14 @@ The class documentation uses [JSDoc](https://jsdoc.app/) annotations where appli docker exec -u root -it ph-municipalities npm run docs:build ``` -### Using NodeJS +
+ +
+ +
+ + Using NodeJS + 1. Install the dependencies for JSDoc. Refer to the [**`npm run generate-docs`**](#npm-run-generate-docs) Script usage for more information. 2. Copy Bash scripts to the **/app** directory. @@ -587,11 +694,16 @@ The class documentation uses [JSDoc](https://jsdoc.app/) annotations where appli ./scripts/docs-build.sh ``` +
+ ## Troubleshooting This section describes several common errors and related fixes. -### EACCESS: permission denied +
+ + EACCESS: permission denied + #### Information @@ -607,7 +719,9 @@ This section describes several common errors and related fixes. `sudo chown -R : ./app` 3. Re-run the NPM script. +
+
@ciatph
20220807 \ No newline at end of file