docs: add notification section to customize and reference

[rekt-hard]

❤️ Thank you for your contribution!

Description

closes inveniosoftware/invenio-app-rdm#2204

Adds notification documentation to the reference and customization sections.

Checklist

Ticks in all boxes and 🟢 on all GitHub actions status checks are required to merge:

• I'm aware of the code of conduct.
• I've created logical separate commits and followed the commit message format.
• I've added relevant test cases.
• I've added relevant documentation.
• I've marked translation strings (for relevant code).
• I've followed the CSS/JS and React guidelines (for relevant code).
• I've followed the web accessibility guidelines (for relevant code).
• I've followed the user interface guidelines (for relevant code).
• I've identified the copyright holder(s) and updated copyright headers for touched files (>15 lines contributions).
• I've NOT included third-party code (copy/pasted source code or new dependencies).

Third-party code

If you've added third-party code (copy/pasted or new dependencies), please reach out to an architect.

Reminder

By using GitHub, you have already agreed to the GitHub’s Terms of Service including that:

1. You license your contribution under the same terms as the current repository’s license.
2. You agree that you have the right to license your contribution under the current repository’s license.

[ppanero]

Massive work! Thanks a lot! I have two main comments:

• The cuzomize part talks about the notification backends and builders but does not specify what they are. While I do agree that might not be the place to do so, pointers to the respective reference sections would help on navigating it.
• The reference sections starts already mentioning backends and builders from the first paragraph. However, those concepts have not been introduced and makes is a bit hard to follow. The end result is that all the pieces are not put together until the end. (biased opinion now...) I am more a fan of gradually introducing the concepts (i.e. in the first paragraphs you can put a one line definition to people can understand what you are talking about, then it gets fully explained later on).

[rekt-hard]

Thank you for taking the time to read through this 🙏
In the first paragraph, added a sentence and a link each for backends, builders and resolvers. Also addressed all other comments.

Will add a section to features-walkthrough once the UI PR is in

[alejandromumo]

Left minor questions

[rekt-hard]

Notifications walk-through page

[Samk13]

// Suggestion: Include the config variable name for users to set notifications on by default, overriding the current 'off' default setting.

[Samk13]

Suggestion:
Email notifications lack port in links if it's not explicitly added in either config:

SITE_UI_URL = "https://127.0.0.1:5000"
SITE_API_URL = "https://127.0.0.1:5000/api"

or cli (e.g. invenio-cli run --port 5000). The celery worker appears to struggle to read the current port value. Therefore, to me, it's a good idea if we document that specifying the port number is necessary for the proper functioning of notification links."

[jrcastro2]

LGTM!

[zzacharo]

Hey @rekt-hard, I will summarize here what we discussed IRL:

• Let's split the PR to 2 based on the audience, i.e users and developers
• I would take inspiration from the existing examples of custom fields and administration panel on how to expose the feature documentation based on a real example so users can relate and gather the information they want
• User audience:
  • Feature walkthrough: High level overview of the notifications feature. A user should quickly understand what is this feature about, maybe with an example.
  • Customize: I think users cannot customize notifications without developing experience so I would not add a section there. If that's not the case then we can add it!
• Developer audience:
  • Reference: I would keep only the notification classes definitions with explanations of the properties and methods if it makes sense
  • Architecture: I would explain there the notifications feature from the design perspective. For example give the dictionary of the involved entities i.e receiver, backend etc. Inspiration could be the Events handling.
  • Develop/Topic guide: I would explain there how you can build your own notification backend (if that's the case currently or omit otherwise)
  • Develop/ How to: Maybe add there how I can change the notification template or other configurable parts of the feature

We had a really nice tutorial in the past on general information on how to write documentation that personally I always go back and refresh my memory 😅 You can find it here if you think is useful for you https://inveniordm.docs.cern.ch/maintenance/documentation/.