doc: Initialize documentation

[oxzi]

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

[oxzi]

To build the docs, please refer to this PR: Icinga/icinga-docs-tools#9

[julianbrost]

Where will be documented how to connect the daemon to Icinga 2? Do you see this as part of the Notifications Web documentation as that provides the config form? Even if that will be the case, a hint on this somewhere might be nice.

[oxzi]

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

[oxzi]

(This note is not related to this file in particular, I just wanted to create a thread and don't know another way to do this here.)

I am a bit unhappy with the numbering of the markdown files by their filename. This layout was copied from the other Icinga documentations and I would expect a certain degree of similarity between the projects.

However, this layout enforces a ordering by the names from the beginning, which is hard to change later, as it will break links, resulting in dead URLs. For example, in Icinga DB I once wanted to add a new section between two already existing ones, but there is no real possibility to add something in between¹.

It would be possible to leave greater gaps, but this would also look weird. I would like to hear your comment on this, @julianbrost. Thanks :)

Footnotes

1. Except of hacks like naming something 03-01-Foo.md if it should go between 03-Configuration.md and 04-Upgrading.md. ↩

[oxzi]

This layout was copied from the other Icinga documentations and I would expect a certain degree of similarity between the projects.

If we would consider breaking our own conventions, we could manually populate MKDocs' nav and don't prefix files with numbers. This, however, would also require patching the build-docs.rb script.

[julianbrost]

To be honest, I never thought about this. But indeed, it doesn't really make sense to me that the URL for example is https://icinga.com/docs/icinga-2/latest/doc/14-features/ instead of just https://icinga.com/docs/icinga-2/latest/doc/features/.

we could manually populate MKDocs' nav and don't prefix files with numbers. This, however, would also require patching the build-docs.rb script.

I'm not familiar with MKDocs either, so I don't know what its nav is, but it doesn't sound wrong to me.

By the way, leaving gaps wouldn't be unheard of, see https://github.com/Icinga/icingaweb2-module-director/tree/master/doc and https://github.com/Icinga/icinga-powershell-framework/tree/master/doc for example.

[ncosta-ic]

Indeed, proper permalinks regardless of the given file name, would be really handy. There's a whole discussion about it over at squidfunk/mkdocs-material#3758

The whole build-docs.rb wrapper is pretty hacky alltogether and even destroyed my local git repository because of the wonderful rm -rf instruction contained in it...
A better solution would be to rewrite our existing build-docs.rb functionality into a Python hook¹.
We could also include our own solution to the url problem by doing so.
I would be up for that task as I have a lot of experience with Python - if we were to decide to go for such a change.

Footnotes

1. https://www.mkdocs.org/user-guide/configuration/#hooks ↩

[julianbrost]

I'm all for improving things there if you've looked into it already and have ideas how to do it better. But sounds something to better track in central place rather than here. If we change something, that would affect most projects anyways. Also, this shouldn't block anything here, the only question is whether you want to add gaps in the numbers for the moment.

By the way, keeping URLs working with a change in that direction should be simple by redirecting NNN-foobar to foobar.

[oxzi]

For the moment, I added some gaps between the numbering of the later sections as one might expect something to pop up there.

After some potential future change, a simple RewriteRule ^/doc/([a-z0-9-]+)/[0-9]+-(.*) /doc/$1/$2 [R]¹ should do, as @julianbrost also suggested.

Footnotes

1. Untested, of course 🙃 ↩

[oxzi]

#223 would change the following URLs. However, this isn't a blocker as a subsequent PR can update this.

[julianbrost]

In general, fine for me now. (To be fair, I didn't cross check with the web documentation for possible duplicates, but I wouldn't expect any of what's in here to be duplicated apart from the about page where it's to be expected.)

Just that one obvious thing, but better have it as an unresolved conversation than accepting and forgetting it:

[oxzi]

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

[oxzi]

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.

[yhabteab]

Looks perfect TM.

[ncosta-ic]

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]

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¹ 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.

Footnotes

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]

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.