Icevision: Deployed docs do not match current release

Created on 20 Mar 2021 · 12Comments · Source: airctic/icevision

🐛 Bug

Docs are deployed whenever we push to master. This means the content may not match what is released and lead to confusion.

For example, right now the custom parser tutorial live on the website contains the new API syntax for the unreleased version 0.7. This will not match what you need to do from the released version.

Perhaps we should only deploy on release?

bug

Source

jerbly

Most helpful comment

I don't see why this can't work in a github action. We can pin mike to a commit that we know works. I'm going to make small project to prove this working through actions before putting it live in IceVision/IceData. (We should probably assign this ticket to me I guess?)

jerbly on 25 Mar 2021

🚀1 👍1

All 12 comments

We need to get the version selection option on our docs, similar to what we have in lightning here.

Is this something done by the host (github/readthedocs) or by the documentation engine (mkdocs/sphinx)?

lgvaz on 22 Mar 2021

readthedocs does it: https://docs.readthedocs.io/en/stable/versions.html
Looks like we're using Material for MkDocs at the moment. There's a guide on versioning here: https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/ - I'll see if I can figure out what we need to do.

jerbly on 23 Mar 2021

👍2

So what you're saying is that we can do this either with readthedocs OR with mkdocs?

lgvaz on 23 Mar 2021

Yeah... I was going to make a quick project to test how it works with mkdocs-material since that's what we're using for IceVision at the moment.... seems the quickest win. You end up with a little drop down with the version number in it top-left. See: https://jimporter.github.io/bfg9000/latest/ for example.

jerbly on 23 Mar 2021

I took a look at the plugin here, so if I understood correctly, this is what we will have to do:

We have the github workflow mk-docs-build.yml that currently does mkdocs gh-deploy --force every-time we push to master, we would change that to mike deploy 0.7 latest (question: can we keep re-deploying to 0.7 on every push to master?).

I would actually like to do mike deploy latest if possible, and then on a release (which we trigger on github) we would do mike deploy version (the version comes from the tag of the release).

lgvaz on 24 Mar 2021

I've been looking at this too. And I think what you've said there is correct. I think a nice pattern is to have a latest and a dev like the https://jimporter.github.io/bfg9000/latest/ (and it's totally weird but the version numbers on that project happen to match exactly where we are!!) So exactly like bfg9000 we would have 0.6 (latest) and 0.7 (dev) - (note, this sets the next version ahead of time that I talked about in another thread somewhere) and it's dev that follows master.

One thing that's not clear to me yet is whether this works with mkdocs-material or if you need mkdocs-material-insiders which is a pay-for option.

jerbly on 24 Mar 2021

One thing that concerns me is that neither mike or bfg9000 have a github workflow to deploy the docs.

he version numbers on that project happen to match exactly where we are!!

hahahahahahah yeaah!

or if you need mkdocs-material-insiders which is a pay-for option.

is there something you found in the package that created this doubt?

lgvaz on 24 Mar 2021

So I made this work locally without "insiders". I needed to upgrade mkdocs-material to the latest. Unfortunately I then needed to get the unreleased master of mike :vomiting_face: for it to all work.