How to update the documentation for a version?

[swcurran]

We have an existing project repository, and a new documentation repository/site that is derived from it. To do that, we have a script that copies markdown files from the project repo at a given tag, into the docs repository in a branch corresponding to the project release. Then, we tag the branch, which triggers Mike to make a set of pages for the version in the gh-pages branch.

• Project repo has a release 0.8.1
• Add a branch in docs repo 0.8.1 and make updates to a script, copying files from tag 0.8.1 in the project repo
• Create a release by tagging v0.8.1 on branch 0.8.1
• That triggers a 0.8.1 and v0.8.1 docs site folder

All good, except that we're still evolving the script and from time to time we need to regenerate the site pages for a given version. We thought that we could:

• update the branch in the docs repo
• delete the release and tag

That triggers Mike to generate the site pages. However, the resulting pages remain at the state of the original version site pages.

Is there a way to have Mike generate the site folder based on the current tag vs. what the tag was initially?

• Project: https://github.com/hyperledger/aries-cloudagent-python
• Docs Repo: https://github.com/hyperledger/aries-acapy-docs

[jimporter]

You can always update a particular version of documentation via mike deploy VERSION. Just run that from a checkout of your source .md files, and it will build and commit them to the VERSION/ subdirectory on your gh-pages branch. Then you just need to push upstream (e.g. via the --push flag).

Is there a way to have Mike generate the site folder based on the current tag vs. what the tag was initially?

So long as you have the correct revision of your source documentation checked out, mike will do all this automatically. In fact, looking at your commit logs, everything appears as it should. I don't see any problems with the deployments.

[swcurran]

Thanks. I've updated the GHAction to do a mike delete ${VERSION} before the mike deploy.... That seem to improve things -- I'm seeing some changes. But oddly, one specific change -- an override for the version -- is not showing up.

I'll keep playing...

[jimporter]

Thanks. I've updated the GHAction to do a mike delete ${VERSION} before the mike deploy.... That seem to improve things -- I'm seeing some changes.

That shouldn't be necessary. Internally, mike deletes the previous revision of the docs before committing the new revision.

But oddly, one specific change -- an override for the version -- is not showing up.

I'm not sure what an override is in this context.

[swcurran]

OK — I’ll remove that and try to see what is taking affect and what isn’t. The “overrides” is part of mkdocs material, so it should be applied on building the docs.

Up until now I’ve only been using mike via GHA on the docs repo, since almost everything is just working. I’ll try to get it running locally — that should help me debug things, I think.

[swcurran]

Solved my issue and it was nothing to do with Mike. All self-inflicted! Doh...

Sorry for the issue and thanks for the confirmation on how mike works.

[jimporter]

Cool, glad everything is working now!