Move documentation to versioned repo?

[fnoop]

Currently docs are held within the docs/ folder of the maverick repo. Github pages are then used with the master branch option. However, this only allows a single version of docs to be served, and work-in-progress docs are served as the live docs. Should be able to work on next version of docs along with next version of code while still having a stable version of docs served. Or, would be nice to have a history of versioned docs, perhaps by making subfolders within doc folder, named by version.

[SamuelDudley]

I like the versioned docs idea... We could host the docs on an external site (docs.goodrobot.org ?) and have the pages an webserver code in the Maverick repo (possibly as a submodule?). Links to old docs would point to old versions of the page with a notice that the user is not viewing the current release docs.

[SamuelDudley]

https://bokeh.pydata.org/en/0.12.10/

[cglusky]

concur about versioned site files. to be clear - are we talking about running github pages from a master branch vs running from a /docs subdir in a master branch?

eventually a good way for us to eat our own dog food when it comes to front end dev.

if we go this way the first step is goodrobots.github.io repo correct?

[fnoop]

I've tried running github pages from gh-pages branch and from /docs subdir - they both effectively behave the same way because it updates the public docs as you update the branch. There's no 'master' branch behind the scenes that you can push to stable, which is a stupid lack of workflow (imho). To note, I've used docsify (https://docsify.js.org/#/) so far, because it looks nice, it's very lightweight and quick to use, and it doesn't require a webserver - that is, it can run from a local folder or just use a webserver to serve out static files, it doesn't require any dynamic interpreter. The goal is to have it available in the browser completely offline (as a PWA), but it doesn't work very well so far (https://github.com/QingWei-Li/docsify/issues/289). I'm open to moving it if there is a significantly better alternative. Having the docs offline when you're in the field is a big +.

[fnoop]

One possibility I was thinking of is to have a separate maverick-docs repo, and mirror the release branches. Another possibility is to have a separate repo with subdirectories for each version. Not sure we need separate versions of docs for each version of maverick, but a separate master/stable would be very useful.

[SamuelDudley]

If a separate docs repo is used could it be added as a submodule to automatically capture the correct doc commit hash for each particular release version of maverick?

[SamuelDudley]

So for every release of maverick you would commit the submodule update of the docs just prior. That way the correct doc commit hash is checked out along with the maverick version. +1 for offline capable docs.

[fnoop]

I read that submodules are more trouble than they're worth so studiously ignored them up to now (but open to it if that's the best way). One deployment option is to use maverick itself to manage the documentation - add a manifest to manage the git clone of the docs of a specific version (probably easiest to just match the version of maverick) into a specific point in the webserver doctree. In fact there's already a mechanism for doing this: https://github.com/fnoop/maverick/blob/stable/manifests/maverick-modules/maverick_web/manifests/maverick_docs.pp The git clone bit is commented out currently because the docs are already a subdirectory of the main maverick repo at the moment.

[fnoop]

Another method is to use the maverick self-update mechanism or something similar from the main maverick wrapper/shell script: https://github.com/fnoop/maverick/blob/stable/bin/maverick#L244 This updates maverick itself from github, but also maverick-fcs (maverick-fcs is where the webserver doctree currently comes from, 'Flying Control Station')

[SamuelDudley]

One benifit of using submodules for this task would be that the docs still exist in the maverick git repo on github (github will follow the submodule link). Using the scripted clone after technique just means we will need to manage the version links in the readme to provide access to the correct doc version. Regardless of submodule vs no submodule ultimately a seperate repo is required for the docs so perhaps we can start there?

[fnoop]

Yes sure, let's start with the separate repo, we can work out the details later. I've no idea what the best way will be!

[SamuelDudley]

Okay, that raises the question of maverick only docs or make a goodrobots docs that contains the maverick docs in a section? I don't know what the other sections will be but just a thought...

[cglusky]

are we thinking full on progressive web app for the docs and offline?

[fnoop]

Yes, ideally. Full PWA absolutely for the main web ui, if we can do it for the docs as well bonus points.

[fnoop]

Interesting alternative for docs from facebook: https://docusaurus.io/docs/en/versioning.html