Feature: Access to Multiple Versions of the RMG Documentation

[amarkpayne]

Motivation or Problem

Currently, the RMG documentation on the website is based on the current version of master. This can create problems when a user who installed the "binary" version of RMG looks at the documentation, as there can be changes that don't apply for their installation. While it is of course possible to make the documentation from your current installation, this is not ideal.

Desired Solution

When someone goes to the documentation page of the RMG website, they should either be prompted to choose which version of RMG they are using, or they should have the ability to change to other versions of the documentation. Ideally, we would have the option for all releases as well as the current version of master, but it would be okay if we don't host versions of the documentation that are very old.

Potential Solutions

• This appears to be a common feature for many other software projects that use sphinx, so we should look here first to see if sphinx can help with this

• Worst case, we could manually setup this up on the RMG server by making the documentation for different versions in different folders, but this far from ideal.

Going Forward

By opening this feature issue, I would like to get the conversation going about what we want to implement and more importantly as a place to document our findings about different ways we might try to implement this. Please feel free to share your thoughts/ideas/findings below.

[xiaoruiDong]

Thanks for the advice! This is an awesome idea. As we are doing a huge transition from py2 to py3, settings, argument names and many other things are changed. Given many users may be still using py2 version RMG, it is indeed desirable to keep multiple version versions of the documentation available.

To me, a desirable implementation is that: when we click the 'documentation' button on the RMG website, we will be directed to the documentation for the newest version. But we have choices to switch to any previous version of the documentation as well. It can be

1. a section below the 'Quick Search' used to display the versions can be switched to
2. a link in the 'Quick reference guide' and commented as 'want to find the documentation of previous versions of RMG?'. Then users will be redirected to a page showing the list of previous versions of the RMG documentations.
3. .... (advice are welcomed)

I will first try to understand how sphinx can help with this, and based on the understanding, propose a solution (like the items shown above).

[amarkpayne]

Thanks for looking into this @xiaoruiDong ! Let me know what you find

[amarkpayne]

@xiaoruiDong do you think you'll have time in the coming weeks to look at this further? This comes up often with the new restart feature (see ReactionMechanismGenerator/RMG-Py#1902). Let me know what your thoughts are or if I can help

[mliu49]

It might be worth transferring the documentation to https://readthedocs.org/. They offer support for automatic builds and versioning. I haven't looked at the details of how to set it up, but it seems like they might be able to connect directly to the GitHub repo, pull the code, and build the documentation.

If you choose to do that, we should set up the RMG-Py gh-pages site to automatically redirect if possible.

[xiaoruiDong]

Thanks for bringing this back. Actually I did some trials to build our documents on https://readthedocs.org/ once a while, but not succeeded. I think it is due to the resource limitation, but not fully sure. @amarkpayne If you don't mind, we can spend some time investigating this next week.

[alongd]

ARC's documentation is stored in github.io (https://reactionmechanismgenerator.github.io/ARC/index.html) and also has automated API deployment. Perhaps consider remaining in github