diff --git a/.vuepress/config.js b/.vuepress/config.js index f89d7a59..d222fed3 100644 --- a/.vuepress/config.js +++ b/.vuepress/config.js @@ -67,14 +67,23 @@ export default { text: "Module Development", collapsible: true, children: [ - "/development/introduction.md", - "/development/core-module-file.md", - "/development/node-helper.md", - "/development/helper-methods.md", - "/development/logger.md", - "/development/notifications.md", - "/development/weather-provider.md", - "/development/documentation.md", + "/module-development/introduction.md", + "/module-development/core-module-file.md", + "/module-development/node-helper.md", + "/module-development/helper-methods.md", + "/module-development/logger.md", + "/module-development/notifications.md", + "/module-development/weather-provider.md", + "/module-development/documentation.md", + ], + }, + { + text: "Core Development", + collapsible: true, + children: [ + "/core-development/introduction.md", + "/core-development/testing.md", + "/core-development/debugging.md", ], }, { diff --git a/.vuepress/enhanceApp.js b/.vuepress/enhanceApp.js new file mode 100644 index 00000000..199f3979 --- /dev/null +++ b/.vuepress/enhanceApp.js @@ -0,0 +1,12 @@ +export default ({ router }) => { + router.addRoutes([ + { path: '/development/introduction.html', redirect: '/module-development/introduction.html' }, + { path: '/development/core-module-file.html', redirect: '/module-development/core-module-file.html' }, + { path: '/development/node-helper.html', redirect: '/module-development/node-helper.html' }, + { path: '/development/helper-methods.html', redirect: '/module-development/helper-methods.html' }, + { path: '/development/logger.html', redirect: '/module-development/logger.html' }, + { path: '/development/notifications.html', redirect: '/module-development/notifications.html' }, + { path: '/development/weather-provider.html', redirect: '/module-development/weather-provider.html' }, + { path: '/development/documentation.html', redirect: '/module-development/documentation.html' } + ]) +} diff --git a/README.md b/README.md index 5d265801..54c66900 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ title: Introduction --- -![MagicMirror²: The open source modular smart mirror platform. ](./.vuepress/public/header.png) +![MagicMirror²: The open source modular smart mirror platform. ](/header.png)

diff --git a/core-development/debugging.md b/core-development/debugging.md new file mode 100644 index 00000000..fbe92468 --- /dev/null +++ b/core-development/debugging.md @@ -0,0 +1,117 @@ +--- +title: Debugging +--- + +# Core Development Documentation: Debugging + +Tips and tricks for debugging MagicMirror², + +## Make sure dependencies are up-to-date + +When you pull a branch, exceptions can be thrown when running MagicMirror²: + +``` +App threw an error during load +Error: Cannot find module 'ansis' +Require stack: +``` + +If this happens, make sure that dependencies have been updated to latest by +executing `npm install`. + +## Breakpoints + +Node.js has support for +[built-in breakpoints](https://nodejs.org/api/debugger.html), or +[VSCode](https://code.visualstudio.com/) allows for visual breakpoints and +inspecting of objects. + +Developer consoles in browsers and the Electron app (typically CTRL+SHIFT+I to +toggle open/close) can be used to set client-side breakpoints, step through +scripts and inspect variables. + +## Logging + +While there are no log files produced by the server, info is reported in two +different places: + +- The console when running from `npm run start` or `npm run server`. + - This is separated into two streams, `console.log()` is output as the + `stdout` stream, and + - `console.error()` is output as the `stderr` stream. + - These can be redirected to files when starting the server. `>` will redirect + `stdout`, and `2>` will redirect `stderr`. `2>&1` will combine both streams: + `npm run start > out.log 2>&1` +- The browser's developer console (typically CTRL+SHIFT+I to toggle open/close) + will have output from scripts that run on the browser. + +The [MMM-Logging](https://github.com/shbatm/MMM-Logging) module can help to +gather logs and output to a file, but at a performance cost. + +Debug logging is disabled by default, and can be very verbose. It can be enabled +in the _config/config.js_ file by adding `"DEBUG"` to the `logLevel` key: + +```js +let config = { + // ... + logLevel: ["INFO", "LOG", "WARN", "ERROR", "DEBUG"], // Add "DEBUG" for even more logging + // ... +}; +``` + +If you are using `pm2` to launch MagicMirror², you can use the `logs` command to +display lines from each of the `stderr` and `stdout` streams, but not interlaced +by time: + +```sh +pm2 logs --lines=15 # will show 15 lines each from stdout and stderr +``` + +There is no capability to identify the module that is producing console output. +However, most browsers have the ability to filter logs by a string. + +## Date + +It can be very useful to set the current date to debug calendar issues. In order +to do this, override `Date.now` with a lambda in _config/config.js_: + +```js +Date.now = () => new Date("2023-12-31T14:05:32").valueOf(); +``` + +This will cause every request for the current time to return the specified time, +at least for the core and built-in modules. + +Several tests use this to override the current time for the test. See +`startApplication()` in _tests/electron/helpers/global-setup.js_ as it has a +`systemDate` argument to override the system date for tests. + +**NOTE:** Some modules may use `new Date()` to get the current date/time, though +this is not recommended. If this is the case, the external module will not work +correctly for date debugging. + +## Timezone + +The `TZ` environment variable can be used to specify a valid +[canonical timezone name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) +from the [tz database](https://en.wikipedia.org/wiki/Tz_database). + +Several tests do this, such as this example in +_tests/electron/helpers/global-setup.js_: + +```js +process.env.TZ = "GMT"; +``` + +The _package.json_ could also be modified to force a timezone for a given +script, such as `start:dev`: + +```json +"start:dev": "TZ=Europe/Madrid ./node_modules/.bin/electron js/electron.js dev" +``` + +Or when running from the command line (Linux example): + +```sh +TZ=Europe/Madrid npm run start:dev +``` diff --git a/core-development/introduction.md b/core-development/introduction.md new file mode 100644 index 00000000..2aa82d41 --- /dev/null +++ b/core-development/introduction.md @@ -0,0 +1,48 @@ +--- +title: Introduction +--- + +# Core Development Documentation + +This documentation describes core MagicMirror² development. + +## General + +MagicMirror² is a community-driven development effort, and +[contributions](../about/contributing.md) are welcome! + +In general, new features and bug fixes should be tracked against an +[issue in the MagicMirror repo](https://github.com/MagicMirrorOrg/MagicMirror/issues). +It is always a good idea to search existing issues to see if a problem you're +experiencing has already been reported, or if someone has already suggested a +feature you'd like to propose. Creating or finding an issue also starts the +discussion and helps build consensus around your proposed fix or feature. + +The MagicMirror² core is +[developed on GitHub](https://github.com/MagicMirrorOrg/MagicMirror/) out of the +_develop_ branch. To begin developing MagicMirror² core, please fork the GitHub +project and create a new branch based off of the _develop_ branch. + +When your development is ready for review and testing, create a new _Pull +Request_ targeting the _develop_ branch. The development team and other +contributors will be able to review your changes and provide feedback, and the +test system will run automated tests against your changes. Make sure to mention +the issue(s) that your Pull Request solves. + +## Development Environment + +Although Node.js applications are typically platform-independent, many of the +scripts created for MagicMirror² are Linux-based. While Windows/Mac development +is possible, you may run into issues. (Improvements here are welcome!) + +You will need to have [Node.js installed](https://nodejs.org/en/download). When +doing Linux development, on newer distributions Node.js is available from +package managers. + +Many Node.js or experienced Javascript developers have an environment that works +for them. New developers to Node.js / Electron can download +[VSCode for free](https://code.visualstudio.com/download) and use many +extensions available for debugging and developing Javascript. + +Also checkout +[Building Node.js Apps with VSCode](https://code.visualstudio.com/docs/nodejs/nodejs-tutorial). diff --git a/core-development/testing.md b/core-development/testing.md new file mode 100644 index 00000000..65bf30d8 --- /dev/null +++ b/core-development/testing.md @@ -0,0 +1,34 @@ +--- +title: Testing +--- + +# Core Development Documentation: Testing + +Unit tests are important to ensure the quality of the project as changes occur. + +All tests are located in the +[_tests_ top-level directory](https://github.com/MagicMirrorOrg/MagicMirror/tree/master/tests). + +## Hierarchy of Tests + +Below the _tests_ directory are other directories that organize the tests: + +- _configs_ - Configuration files for tests. +- _e2e_ - End-to-end tests that start and run MagicMirror² in various + configurations. +- _electron_ - Electron application tests. +- _mocks_ - Mock-up data for tests. +- _unit_ - Unit tests for utilities and smaller portions of MagicMirror². +- _utils_ - Testing utilities. + +## Writing a Test + +Almost all pull requests must have test coverage of changes. Usually, it is +easier to find an existing test and extend it to test your new functionality. + +For example, if you were writing a test for a fix in the Calendar module, you +might locate _tests/e2e/modules/calendar_spec.js_ and add an additional test +there. + +If you have questions about how to write a test, you can also ask in the +[MagicMirror forums](https://forum.magicmirror.builders/). diff --git a/development/core-module-file.md b/module-development/core-module-file.md similarity index 100% rename from development/core-module-file.md rename to module-development/core-module-file.md diff --git a/development/documentation.md b/module-development/documentation.md similarity index 100% rename from development/documentation.md rename to module-development/documentation.md diff --git a/development/helper-methods.md b/module-development/helper-methods.md similarity index 100% rename from development/helper-methods.md rename to module-development/helper-methods.md diff --git a/development/introduction.md b/module-development/introduction.md similarity index 94% rename from development/introduction.md rename to module-development/introduction.md index 73178ebe..e9173518 100644 --- a/development/introduction.md +++ b/module-development/introduction.md @@ -21,6 +21,9 @@ information in your README file.** - What external API's it depends upon, including web links to those - Whether the API/request require a key and the user limitations of those. (Is it free?) +- **Do not use `new Date()` for the current timestamp, instead prefer + `new Date(Date.now())` as it can be more + [easily overridden for debugging](../core-development/debugging.html#Date)**. Surely this also help you get better recognition and feedback for your work. diff --git a/development/logger.md b/module-development/logger.md similarity index 100% rename from development/logger.md rename to module-development/logger.md diff --git a/development/node-helper.md b/module-development/node-helper.md similarity index 100% rename from development/node-helper.md rename to module-development/node-helper.md diff --git a/development/notifications.md b/module-development/notifications.md similarity index 95% rename from development/notifications.md rename to module-development/notifications.md index 4abfef34..cbd993ab 100644 --- a/development/notifications.md +++ b/module-development/notifications.md @@ -8,10 +8,10 @@ The MagicMirror core has the ability to send notifications to modules. Or even better: the modules have the possibility to send notifications to other modules. Additional technical information on the notifications can be found in the -[modules' documentation](/development/introduction.md#general-advice): +[modules' documentation](/module-development/introduction.md#general-advice): -- [notificationReceived](/development/core-module-file.md#subclassable-module-methods) -- [sendNotification](/development/core-module-file.md#module-instance-methods) +- [notificationReceived](/module-development/core-module-file.md#subclassable-module-methods) +- [sendNotification](/module-development/core-module-file.md#module-instance-methods) # System notifications diff --git a/development/weather-provider.md b/module-development/weather-provider.md old mode 100755 new mode 100644 similarity index 100% rename from development/weather-provider.md rename to module-development/weather-provider.md diff --git a/modules/animate.md b/modules/animate.md index a3f4a535..9bda9cda 100644 --- a/modules/animate.md +++ b/modules/animate.md @@ -11,12 +11,12 @@ animation name result. ::: warning Where animation can be used? -- [global module configuration](configuration.md#animated) of a module -- [this.hide()](/development/core-module-file.md#this-hide-speed-callback-options) +- [global module configuration](configuration.html#animated) of a module +- [this.hide()](../module-development/core-module-file.html#this-hide-speed-callback-options) function in core module file -- [this.show()](/development/core-module-file.md#this-show-speed-callback-options) +- [this.show()](../module-development/core-module-file.html#this-show-speed-callback-options) function in core module file -- [this.updateDom()](/development/core-module-file.md#this-updatedom-speed-options) +- [this.updateDom()](../module-development/core-module-file.html#this-updatedom-speed-options) function in core module file ::: diff --git a/modules/calendar.md b/modules/calendar.md index 5cd3c6f5..515d0881 100755 --- a/modules/calendar.md +++ b/modules/calendar.md @@ -30,7 +30,7 @@ The following properties can be configured: | `maximumNumberOfDays` | The maximum number of days in the future.

**Default value:** `365` | | `pastDaysCount` | The number of days of which events in the past should be displayed.

**Default value:** `0`
`NOTE: this value is advisory to any module processing the events broadcast.`
`the default calendar module never displays events from the past` | | `displaySymbol` | Display a symbol in front of an entry.

**Possible values:** `true` or `false`
**Default value:** `true` | -| `defaultSymbol` | The default symbol.

**Possible values:** See [Font Awesome](https://fontawesome.com/v6/search?o=r&m=free) website.
**Default value:** `calendar` | +| `defaultSymbol` | The default symbol.

**Possible values:** See [Font Awesome](https://fontawesome.com/search?ic=free&o=r) website.
**Default value:** `calendar-days` | | `showLocation` | Whether to show event locations.

**Possible values:** `true` or `false`
**Default value:** `false` | | `maxTitleLength` | The maximum title length.

**Possible values:** `10` - `50`
**Default value:** `25` | | `maxLocationTitleLength` | The maximum location title length.

**Possible values:** `10` - `50`
**Default value:** `25` | diff --git a/modules/introduction.md b/modules/introduction.md index 64d49262..6bc3ba0e 100644 --- a/modules/introduction.md +++ b/modules/introduction.md @@ -17,7 +17,7 @@ The following modules are installed by default. For more available modules, check out out the wiki page [MagicMirror² 3rd Party Modules](https://github.com/MagicMirrorOrg/MagicMirror/wiki/3rd-party-modules). If you want to build your own modules, check out the -[MagicMirror² Module Development Documentation](/development/introduction.md) +[MagicMirror² Module Development Documentation](/module-development/introduction.md) and don't forget to add it to the [wiki](https://github.com/MagicMirrorOrg/MagicMirror/wiki) and the [forum](https://forum.magicmirror.builders/category/7/showcase)! diff --git a/modules/weather.md b/modules/weather.md index a37bfcbd..ebd799c1 100755 --- a/modules/weather.md +++ b/modules/weather.md @@ -231,4 +231,4 @@ update. ## API Provider Development If you want to add another API provider checkout the -[Guide](/development/weather-provider.md). +[Guide](/module-development/weather-provider.md).