webthingsio / docs Goto Github PK

Hi,
during installation (on Armbian Buster) I had to install the following additional dependencies, which should be noted in Readme.me:

• python3-setuptools
• • zlib1g-dev (not sure though, if -dev is really necessary or just zlib)

Let me know if I shall file a pull request.

Currently new versions of the documentation are deployed to GitHub Pages with the mkdocs gh-deploy command.

It might be convenient to automate this with a GitHub action so that commits on master trigger deployment automatically.

Recording this here...

I had a quick look into a better documentation system for our online documentation.

My suggestion is that we switch to using MkDocs using the ReadTheDocs theme. MkDocs is one of the two templating engines that ReadTheDocs supports for their free documentation hosting service, but it also supports easily deploying to GitHub Pages.

By using MkDocs with GitHub Pages we can have documentation that looks as nice as ReadTheDocs, but self-hosted at https://webthings.io/docs

It requires following the guide at https://mkdocs.readthedocs.io/en/stable/ and I imagine storing the documentation source in the master branch of our Docs GitHub repo and the generated output on a gh-pages branch. I can then add a /docs submodule to the main webthings.io GitHub repo which tracks the gh-pages branch so that changes make it to the website. For bonus points we could try forking the ReadTheDocs theme to add the WebThings website header navigation to make it feel more like part of the website.

Contributors should still be able to contribute documentation using Markdown as before, the only downside of this setup I can see is that by using git submodules we may have to manually bump the documentation version on the main website repo each time the documentation is edited, which adds an extra step. Mike suggests setting up a GitHub workflow to automate that.

These should match the guides created by Duende as much as possible.

The domain mozilla-iot.org is now owned by a fraudulous group. It's only scam and can be dangerous to unaware users.

For developing addons I like the Docker image a lot. I noticed that the repo is archived, so should the Getting Started Guide be removed or marked as deprecated?