Documentation fixes and improvements

[ukkopahis]

One pull request to gather improvements and fixes to the documentation.

Fixes:

• Dead links corrected
• Markdown formatting errors. The added newlines are required for mkdocs to correctly process formatting.
• Container menu-listing to be alphabetically ordered.

Improvements:

• Pi-hole DNS routing setup and troubleshooting
• How to update containers with git & docker
• Influxdb database creation, retention policy changes, sd-card wear-out prevention
• Home-assistant https reverse proxy and certificate setup using swag to enable google assistant integration
• How to write docs: mkdocs references and testing locally
• Wireguard PEERDNS=auto works together with changes to host's resolveconf.conf
• Add Discord link to Wiki home page

Changes:

• Add top tabs: IOTstack Wiki, Basic setup, Containers, Developers
  (these were chosen in order to be in a sensible alphabetical order)
• Update-related pages organized into the "Basic setup/Updates" subtopic, to make the left menu a bit clearer.
• Files moved to corresponding folders and links updated and redirects from old locations added as not to break existing links on the web.
• Remove custom anchor links and generate them automatically using the "toc" markdown extension. This fixes the blue coloring of the headings, which especially impacts users selecting the dark theme.

Resolves:

• Relevant changes from PR WIP Docs V2 #338 are included, and it can be closed when this is merged.
• Fixes broken link #497
• Fixes pi-hole not setting default password. #500

New top tabs look like this (live version):

And in dark mode:

[ukkopahis]

As a convenience, this and most other recent pull-request are available merged in my repository:
https://github.com/ukkopahis/IOTstack/tree/master/

These changes are also updated to the documentation page available at:
https://ukkopahis.github.io/IOTstack/

[ukkopahis]

Some users could benefit from this and I wouldn't have to link them to my fork...

[Slyke]

Hey @ukkopahis sorry this took so long to review. I've approved it now, but it looks like there are now some merge conflicts. I wasn't able to resolve them myself as I can't push to your remote.

[ukkopahis]

Pull-requests like #489 had changes the same files as this. As such either it or this could be cleanly merged, not both.

Don't know why you couldn't push to my branch. I have "allow edits" ticked:

I've invited you as a collaborator to my fork, maybe that will help in the future.

[ukkopahis]

Github lost your already reviewed changed when I tried rebasing. So here's the conflict-resolution as a merge commit, and a couple new commits.

[ukkopahis]

Summary of additional improvements since the previous review.

• Favicon and logo changed from default to a "stack":
  
• Make Wiki home page a bit nicer:
  
• Fix too long Octoprint title from showing up in the menu
• Small incremental improvements to the way too long "Getting Started" page.
  • Extract talk about sudo into a separate "What is sudo?"-page
  • State the importance of the system patches
  • Add that 64-bits also works and is supported (multiple people on Discord have reported to run it without problems)
• Raise "Updates" to a top-level tab

Post-merge tasks

• you may close WIP Docs V2 #338 as it is superseded by this.

[Paraphraser]

I realise this is a bit late but, on reflection, I think that moving the "a word about sudo" material to another file might not be a particularly good idea. Rolling back the clock a bit to something like 18 months ago, it seemed like 2 out of every 3 problems raised on Discord could be traced back to improper use of sudo. That fell right off once those words went into the getting started doco. Granted, I also added code to many scripts saying "don't run this with sudo" and that probably also had an impact. But the "getting started" document is The Key Document referred to in the primary read-me. That really puts the words about sudo "in ya face" for new users. I'm not sure it will have the same mindshare if it is moved. I'm sure I don't need to tell you the kinds of chaos that can be created from improper use of sudo. People with reasonable Linux experience probably wouldn't make the mistake in the first place but, if they did, would probably be able to recognise the problem and undo the damage. Those aren't the people I worry about. I worry about people who just follow gists and web pages, who see a Pi as a means to an end rather than something they want to develop a deep understanding of, and who get horribly stuck if they make a basic mistake like sudo git clone ... IOTstack and then find nothing works. I'm not saying "put it back". I'm just asking you to keep these comments in mind if there's an uptick in sudo-related problems in issues and on Discord.

[ukkopahis]

But the "getting started" document is The Key Document referred to in the primary read-me

I don't think very long "Getting Started" is user friendly.

it seemed like 2 out of every 3 problems raised on Discord could be traced back to improper use of sudo

Good info. I'll monitor for such problems re-occurring, and correct back if needed.

I'm still planning to:

• extract most from "stack maintenance" to https://sensorsiot.github.io/IOTstack/Updates/ - leaving an executive summary and a link to the Updates page
• New installation/scripted links to how to update docker, not how to script IOTstack install. Remove or fix this, do you have a suggestion @Paraphraser ?
• logging journald errors talks about /etc/docker/daemon.json, which doesn't even exist on my pi. Have to look into log2ram to fix this properly. Maybe move this into a FAQ/common problems page?
• fix all example commands from docker to docker-compose (when possible)