Overhaul documentation

[amotl]

Like https://owntracks.org/booklet/, @jpmens and me would like to use MkDocs together with the respective theme from ReadTheDocs.org to improve the documentation of mqttwarn.

We also talked about restructuring the whole single README.md into different topics, which is long overdue.

[amotl]

@LaborEtArs found it hard to install mqttwarn using its systemd wrapper, see #396. We should improve the situation, either by improving the documentation or by solving #397.

[amotl]

Hi there,

I would like to work on the documentation and finally bring it to Read the Docs. I will post an update here when it's done.

With kind regards,
Andreas.

[amotl]

I've not been able to catch enough time to work on this topic here, but I've practiced it elsewhere just recently. It does not require much effort, infrastructure-wise. Editing the content and bringing it into a better shape for general consumption is a different beast of course, and will take a day or two.

I love the Furo theme, and would also use it for the published documentation of mqttwarn, when there are no objections.

• https://luftdatenpumpe.readthedocs.io/
• https://phenodata.readthedocs.io/

[amotl]

Hi. I've finally made a start on this with GH-636. It will definitively need some more polishing, but the existing content is there, and looks nice already. Enjoy.

https://mqttwarn.readthedocs.io

[amotl]

Hi again,

the previous single-page HANDBOOK.md has grown to almost 4000 lines, and became unbearable. It has been dissolved now.

The three main pillars of documentation, where most content has been refactored to, are "Services", "Topics", and "Transformations" now, resembling the very core of mqttwarn. You will find them at the "Configuration" section of the documentation ¹. On the other hand, the grand catalog of notifier plugins is now on a dedicated page ², and it's still single-page, because tearing it apart would also be unbearable.

While working on the refactoring, I've diligently edited each and every piece of text I've actually moved, applying spring-cleaning-like tasks, and adjusting phrasing and wording towards active voice. The same kind of editing should also be applied to the single-page notifier catalog, which has been moved over verbatim. However, I will not have the capacity for that right now, so I am postponing it to a subsequent iteration.

Please advise any kind of feedback, now is the right time.

With kind regards,
Andreas.

Footnotes

1. https://mqttwarn.readthedocs.io/en/latest/configure/ ↩

2. https://mqttwarn.readthedocs.io/en/latest/notifier-catalog.html ↩

[amotl]

Oh, by the way. Is "mqttwarn" actual the correct spelling? I believe I've also seen it to be written MQTTwarn elsewhere, but I may be wrong. In this regard, in order to fix eventual mistakes made by me while maintaining mqttwarn, it would also be the right time to raise your hand.

/cc @jpmens, @sumnerboy12

[jpmens]

I think we've typically spelled it mqttwarn with the MQTT lowercase.

[sumnerboy12]

I would agree with that.

[amotl]

Thanks. Everything is all right then.

[amotl]

Hi again,

after bringing the documentation into a better shape and publishing it ¹, there are a few backlog items needed to be resolved before closing this issue. I will enumerate them below. For resolving some of them, I am humbly asking for your support as a repository owner, @jpmens.

With kind regards,
Andreas.

---

• Disable GitHub Pages configuration. It looks it is currently still active, but failing ², and I don't know how or where to turn it off. -- https://github.com/jpmens/mqttwarn/actions/workflows/pages/pages-build-deployment
• Enable access to Read the Docs project ³ for @jpmens.
  You can easily use "Sign in with GitHub" on the Read the Docs » Login page. After that, I will probably be able to add you as a member to the project. Otherwise, please tell me your account name on RTD, if you have one already. Thanks!
• Enable CI/GHA integration with Read the Docs.
  Read the Docs offers excellent integration with CI/GHA I would not like to miss, see Read the Docs » Pull request builds. I've configured the RTD project already to "Build pull requests for this project". However, RTD would still need to be connected to the repository on behalf of your permissions, @jpmens, see How to connect your Git repository. Can I humbly ask you to take the steps needed for that? I hope it will not be too much of a hassle.
• Dissolve the Wiki ⁴.
  Screen all pages of the Wiki, and refactor relevant content to the static documentation. Delete the Wiki pages afterwards, or just truncate their contents and add links to corresponding sections at the new documentation location. I feel that is probably my business, as I was the one who started to open that box of Pandora's sister. I already started working on this, and hope to be able to stay focused enough to gradually make progress on that.
• Adjust "About" box on GitHub project page.
  Swap the link to point to the canonical documentation ¹. I also don't have enough permissions to do that.
  

Footnotes

1. https://mqttwarn.readthedocs.io/ ↩ ↩²

2. ↩

3. https://readthedocs.org/projects/mqttwarn/ ↩

4. https://github.com/jpmens/mqttwarn/wiki ↩

[amotl]

Dear @jpmens,

thank you very much for acknowledging my recent patches to mqttwarn. As outlined in my previous post, I would need a bit of your support to improve the CI details on the repository, and to apply further maintenance work. Maybe, if you trust me enough that I will not go too crazy with it, you may also elevate my privileges on the repository? In this case, you will not need to spend any maintenance minutes on it at all, and I will properly inform you about the steps taken, and their outcomes.

With kind regards,
Andreas.

[jpmens]

it says here that I should be able to change your Role, but I can't do anything to the user other than Remove.

I wonder if this is a temporary Github glitch.

[amotl]

I think it might be related to that the repository is on a personal account.

Repositories owned by personal accounts have one owner. Ownership permissions can't be shared with another personal account. [Other users can only be "collaborators"].

Tip: If you require more granular access to a repository owned by your personal account, consider transferring the repository to an organization. For more information, see "Transferring a repository."

-- https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/permission-levels-for-a-personal-account-repository

I usually work with repositories on organization accounts these days ¹², that's why I probably never recognized this would be a problem on the other ones.

Footnotes

1. https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository ↩

2. https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/repository-roles-for-an-organization ↩

[amotl]

In case you would find such a solution acceptable to transfer the repository, I've just invited you to the https://github.com/mqtt-tools organization with ownership permissions. I created this organization the other day, in search for a proper home for the pytest-mqtt package ¹, which is also used within the test harness of mqttwarn.

Footnotes

1. https://github.com/mqtt-tools/pytest-mqtt ↩

[jpmens]

I noticed, thanks, and have already transferred mqttwarn.

[amotl]

That was quick, thanks a stack. I will work on bringing all links back in order now.

[amotl]

Let's also invite @sumnerboy12 to the organization, right?

[jpmens]

I don't think he's still very involved, but let @sumnerboy12 decide if he wants to.

[jpmens]

That was quick, thanks a stack. I will work on bringing all links back in order now.

all links in blogs etc. amended.

[amotl]

PR build integration with RTD now works well, for example at GH-662. Thank you!

---

-- https://mqttwarn--662.org.readthedocs.build/en/662/

[sumnerboy12]

I haven't done much coding with mqttwarn recently but am still using it heavily. Happy to leave with you guys to run the ship!

[amotl]

We will try as good as possible, thanks! Nevertheless, you may still want to accept the invitation I've sent out to you, in order to be able to do stuff in case one of us will not be around.

Also, you may want to add other tools from your own pen to the organization, if they fit into this space. I think if we will come up with a nice logo, it will gradually become a sweet place for a digital garden related to all things MQTT utilities.

[sevmonster]

All the new branding and documentation looks fantastic. My only suggestions would be to split up the notifier catalogue into separate files (e.g. apprise_about + apprise_single + apprise_multi --> notifier_catalogue/apprise.html (and some JavaScript on the remaining notifier_catalogue.html page could redirect based on URI fragment, and a <noscript> elem with a link to the page as fallback).

We also talked about restructuring the whole single README.md into different topics, which is long overdue.

It seems this hasn't been done yet? It looks like the homepage already contains some content from the readme but structured differently/more legibly.

[amotl]

Hi @sevmonster,

currently, there are no plans to dissolve the notifier catalog page ¹. What was important, was to refactor all the other content away from it, and into more appropriate places, which has been conducted already. Thanks for the appreciation.

The reason why I currently do not plan to dissolve the page is because both consuming and editing the single document is so much easier, and there is quite an amount of corresponding work to do on it.

Saying this, corresponding work may happen in the future, maybe on behalf of corresponding Sphinx techniques, but only if we find a way to assemble it back into a single document at rendering time, because, well, consumption is so powerful by being able to use the find-in-page (CTRL+F) feature.

With kind regards,
Andreas.

Footnotes

1. https://mqttwarn.readthedocs.io/en/latest/notifier-catalog.html ↩