From a573fd9841ff0d07111cadfc1b703316fc59a0d8 Mon Sep 17 00:00:00 2001 From: Jokob-sk Date: Sun, 7 May 2023 09:56:37 +1000 Subject: [PATCH] Docs README --- docs/README.md | 85 +++++++++++++++++++++++++++++++ docs/img/GENERAL/in-app-help.png | Bin 0 -> 8876 bytes front/php/templates/footer.php | 11 ++-- 3 files changed, 93 insertions(+), 3 deletions(-) create mode 100755 docs/README.md create mode 100755 docs/img/GENERAL/in-app-help.png diff --git a/docs/README.md b/docs/README.md new file mode 100755 index 00000000..8b8c9832 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,85 @@ +## Documentation overview + +In the app hover-over settings or fields/labels or click blue in-app ❔ (question-mark) icons to get to relevant documentation pages. + +![In-app help](/docs/img/GENERAL/in-app-help.png) + +There is also an in-app Help / FAQ section that should be answering frequently asked questions. + +### 📚 Table of contents + +#### Popular/Suggested + +- [API endpoints details](/docs/API.md) +- [Plugin system details and how to develop your own](/front/plugins/README.md) +- [Network tree map configuration](/docs/NETWORK_TREE.md) +- [Gmail as SMTP server for sending emails](/docs/SMTP_GMAIL.md) +- [Subnets and vlans configuration for arp-scan](/docs/SUBNETS.md) + +#### System Management + +- [Manage devices (legacy docs)](/docs/DEVICE_MANAGEMENT.md) +- [Random MAC/MAC icon meaning (legacy docs)](/docs/RANDOM_MAC.md) +- [Custom Icons configuration and support](/docs/ICONS.md) + +#### Examples + +- [N8N webhook example](/docs/WEBHOOK_N8N.md) + +#### Misc + +- [New Version notifications](/docs/VERSIONS.md) +- [Version history (legacy)](/docs/VERSIONS_HISTORY.md) +- [Invalid JSON errors debug help](/docs/DEBUG_INVALID_JSON.md) + +Feel free to suggest or submit new docs via a PR. + +## 👨‍💻 Development priorities + +Highest to lowest: + +* Fixing core functionality bugs not solvable with workarounds +* New core functionality unlocking other opportunities (e.g.: plugins) +* Refactoring enabling faster implementation of future functionality +* UI improvements + +Design philosophy: Focus on core functionality and leverage existing apps and tools to make PiAlert integratable into other workflows. + +Examples: + + 1. Supporting apprise makes more sense than implementing multiple individual notification gateways + 2. Implementing regular expressions support across settings for validation makes more sense than validating one setting with a specific expression. + +UI specific requests are low priority as the framework picked by the original developer is not very extensible (and afaik doesn't support components) and has limited mobile support. Also I argue the value proposition is smaller than working on something else. + +Feel free to submit PRs if interested. try to **keep the PRs small/on topic** so they are easier to review and approve. + +That being said, I'd reconsider if more people and or recurring sponsors file a request 😉. + +## 🙏 Feature requests + +Please be as detailed as possible with **workarounds** you considered and why a native feature is the better way. This gives me better context and will make it more likely to be implemented. Ideally a feature request should be in the format "I want to be able to do XYZ so that ZYX. I considered these approaches XYZ". + +## ➕ Pull-requests (PRs) + +If you submit a PR please: + +1. Check that your changes are backward compatible with existing installations and with a blank setup. +2. Existing features should always be preserved. +3. Keep the PR small, on-topic and don't change code that is not necessary for the PR to work +4. New features code should ideally be re-usable for different purposes, not be for a very narrow use-case. +5. New functionality should ideally be implemented via the Plugins system, if possible. + +Soem additional context: + +* Permanent settings/config is stored in the `pialert.conf` file +* Currently temporary (session?) settings are stored in the `Parameters` DB table as key - value pairs. This table is wiped during a container rebuild/restart and it's values re-initialized from cookies / session data from the browser. + +## 🐛 Submitting an issue or bug + +Before submitting a new issue please spend a couple of minutes on research: + +* Check [🛑 Common issues](https://github.com/jokob-sk/Pi.Alert/tree/main/dockerfiles#-common-issues) +* Check [💡 Closed issues](https://github.com/jokob-sk/Pi.Alert/issues?q=is%3Aissue+is%3Aclosed) if a similar issue was solved in the past. + +⚠ Please follow the pre-defined issue template to resolve your issue faster. diff --git a/docs/img/GENERAL/in-app-help.png b/docs/img/GENERAL/in-app-help.png new file mode 100755 index 0000000000000000000000000000000000000000..d6d95ba7fde3277a98f582c7bd4c221b1e6e705e GIT binary patch literal 8876 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 TlhXU~V}SdbAdND$hcEsE!!ZY3 literal 0 HcmV?d00001 diff --git a/front/php/templates/footer.php b/front/php/templates/footer.php index bc9f6c14..fd84a334 100755 --- a/front/php/templates/footer.php +++ b/front/php/templates/footer.php @@ -12,9 +12,14 @@ - © 2020 Puche (2022+ jokob-sk)'; - ?> + © + + 2020 Puche (2022+ jokob-sk) + + + Docs + +