Make v1 Documentation Available

[devyntk]

I am unfortunately still bound to using sh v1.14.2 due to reliance on the system-packaged version of sh on Red Hat-based systems. It would be significantly easier to navigate this older version if readthedocs had an old version of sh available. As of yet, my best solution has been using the internet archive to access this documentation, which is a slow and frustrating approach. The previous branch that this was hosted on doesn't seem to exist anymore.

[amoffat]

How does one configure this?

[devyntk]

Readthedocs supports publishing various different versions based off of git tags: https://docs.readthedocs.io/en/stable/versions.html

Because the prior documentation doesn't seem to exist any more, I'm unsure on how you would be able to upload this (without modifying the already existing git tags)

[amoffat]

Oh right, before we were self-hosting the docs on github, from a docs branch (which is now gone). Then we moved to readthedocs. Unfortunately I won't be able to go back. An internet archive is your best bet, or if your project allows, update sh in a virtualenv.

[devyntk]

Unfortunately my project doesn't allow me to update sh, since it'll be installed as a part of our OS provisioning process. Even though the branch is deleted, it looks like you can pull it from the last PRs to that branch, so I've gone ahead and cloned this branch locally to get the documentation. This is theoretically the same as the last change to the gh-pages branch, assuming there were no changes done without PRs. If you merge this in as a branch (eg v1-docs), you could then setup readthedocs to host this prior version.

[amoffat]

Good sleuthing. Would you mind making a pull request for this please?

[devyntk]

I don't believe I have the permissions to create a pull request for this. Since this will need to be a new branch (since the old gh-pages branch has no common history at all with any of the code), it will need to be done with somebody with push permissions to this repo. Github does not allow people to open PRs to new branches (see https://stackoverflow.com/questions/9796370/github-pull-request-to-a-new-upstream-branch)

[amoffat]

Maybe it's easier to just add a note to the current docs if something is different in a 1.* version. There are some key changes but not much else. Could you explain what is out of date for you in the current docs that you need to reference the old docs for?

[devyntk]

The largest different for me & my team is the difference in return types from v1 to v2. We'll often do our local testing in a virtual environment (that will install the latest version of v2 by default), and then attempt to do something like putting the output of a sh Command into json.loads. This will work perfectly fine on v2 since the type returned is effectively a string, and then fail miserably on deploy in v1. There are other smaller differences but this is the major one.

I might suggest moving the MIGRATION.md file into read the docs, and altering it such that it's more of document of differences between v1 and v2. I would also suggest having the changelog in read the docs if possible. I find it confusing to have some amount of documentation in the repo itself, and others in an external website.

I would be happy to potentially work on this migration, though I am inexperienced with sphinx and readthedocs.

[amoffat]

Thanks for offering to work on improving the docs :) I like this idea better than trying to make the old docs work with readthedocs. Moving MIGRATION.md and the CHANGELOG.md into the sphinx docs sounds fine with me, as well any other improvements that help you with v1