Documentation updates

[ryan-summers]

This PR fixes a variety of issues noted in #339 (comment)

This PR also fixes #449 by adding a .gitattributes file that forces the mosquitto config file to be checked out with LF line endings. It appears more recent versions of mosquitto require this.

[svrotter]

I think this should fix most of the issues I pointed out in #339 regarding the getting started section.
As @jordens pointed out in the matrix chat he doesn't consider the setup for a broker on the local machine as relevant at his point, but is there a reason that you didn't touch the miniconf installation in the usage section?

I think we also had some problems there, but @jordens could have to say more about it than me

[ryan-summers]

is there a reason that you didn't touch the miniconf installation in the usage section?

I think we also had some problems there, but @jordens could have to say more about it than me

From what I can tell, the only deviation that was made was to use a python virtual environment, which is really a user consideration IMO. If we want to steer users down that path, we can do so. Curious to hear this either way (I don't typically use virtual environments, but I see their benefits for sure).

[jordens]

IME python venvs are really easy to use, don't need much space and provide an excellent isolation. For example, as a developer you want something like venvs as soon as you are both developing python packages and using them elsewhere. Or if you ever need to isolate yourself from system python packages which may be of a different version etc. And if we use requirements.txt for the manual, that's already tested and synchronized to CI. Even shortens the manual instructions.

[ryan-summers]

@svrotter / @jordens Documentation has now been updated to point users towards using a virtual environment for pip package management

[ryan-summers]

bors try

[bors]

try

Build failed:

• HITL Run Status

[ryan-summers]

bors try

[bors]

try

Build succeeded:

• style
• doc
• HITL Run Status
• compile (stable)

[ryan-summers]

bors merge

[bors]

Build succeeded:

• compile (stable)
• doc
• HITL Run Status
• style