search

Icinga / icinga-notifications

Icinga Notifications: new and improved notifications and incident management for Icinga (work in progress, not ready for production yet)
GNU General Public License v2.0
9 stars 0 forks source link

doc: Initialize documentation #210

Closed oxzi closed 2 months ago

oxzi commented 4 months ago

Both structure and huge parts are copied from Icinga DB and were altered afterwards. The already existing Channel Plugin documentation was extended.

oxzi commented 3 months ago

To build the docs, please refer to this PR: https://github.com/Icinga/icinga-docs-tools/pull/9

oxzi commented 3 months ago

I have made some changes inspired by @ncosta-ic's similar PR over there in web world, Icinga/icinga-notifications-web#218.

oxzi commented 2 months ago

Sorry, while testing the packages together with the docs, I found this faulty username.

oxzi commented 2 months ago

Next to @nilmerg's comments, I have added a sentence to the Big Picture section mentioning other possible sources, as otherwise the text mismatched the image. Furthermore, I have changed the default PostgreSQL credentials in the example configuration to those of the documentation.

ncosta-ic commented 2 months ago

This PR got merged while containing a faulty link.

While a relative link to the LICENSE file works fine for the README.md, it doesn't work for MKDocs (in this case 01-About.md) as it references a file outside of its directory and that file does not get included into the HTML output. This results in a broken link when building it through our Docker image and will thus also fail once added to icinga.com/docs.

icinga-notifications-docs-bug.webm

oxzi commented 2 months ago

This PR got merged while containing a faulty link.

While a relative link to the LICENSE file works fine for the README.md, it doesn't work for MKDocs (in this case 01-About.md) as it references a file outside of its directory and that file does not get included into the HTML output. This results in a broken link when building it through our Docker image and will thus also fail once added to icinga.com/docs.

Are you sure? The same happens in other documentations as well, e.g., for Icinga DB:

https://github.com/Icinga/icingadb/blob/6102d9cb2e30a628ceaf79cc4ba01db1ab50aa8f/doc/03-Configuration.md?plain=1#L4

On the rendered web documentation, the resulting page links to ../../config.example.yml. With its URL being https://icinga.com/docs/icinga-db/latest/doc/03-Configuration/, the destination[^1] still lies within the project's subdirectory.

However, I guess your point is still valid for the documentation's main page, as it might be accessed directly under https://icinga.com/docs/icinga-notifications/ and not …/icinga-notifications/doc/01-About/. Good catch though.

[^1]: https://icinga.com/docs/icinga-db/latest/doc/03-Configuration/../../config.example.yml = https://icinga.com/docs/icinga-db/latest/config.example.yml

ncosta-ic commented 2 months ago

Are you sure? The same happens in other documentations as well, e.g., for Icinga DB ... However, I guess your point is still valid for the documentation's main page, as it might be accessed directly under https://icinga.com/docs/icinga-notifications/ and not …/icinga-notifications/doc/01-About/. Good catch though.

That's correct. And yes, I was wrong about the includes. I blindly checked my Nginx logs instead of just going through the generated html folder. It actually ships the whole git repository and any relative links should work.

The second problem where a user could access the 01-About.md directly under .../latest and not through .../doc/01-About still results in a broken link. But you noticed that as well. Just wanted to clarify my thought process.