benfrancis
commented
6 months ago This is now complete.
It turned out it wasn't necessary to use git submodules, as GitHub Pages can handle hosting at the /docs subdirectory of the root website itself.
Deploying a new version to GitHub Pages can be done with a single command.
$ mkdocs gh-deploy
This does mean that the resources for GitHub Pages are now stored in the gh-pages branch rather than master.
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.