Collect documentation for multiple versions of code

[cmacmackin]

Note entirely sure how we'd do this, but it would be very useful to incorporate links to documentation from old versions, as can be done on ReadTheDocs. I don't think we'd want FORD to rebuild the docs for each version every time it is run. Instead we'd want it to access the old version(s) from somewhere and place them in a subdirectory. It could then offer a dropdown box on the menu bar to select which version of the docs you want to view. The most obvious problem I can foresee is getting paths to files correct. Relative paths would ensure that each version of the docs links to its own copy of each file, but it might be a bit complicated to get the links to other versions working properly, especially for the latest version which would presumably still continue to live in the top of the docs directory rather than within a special subdirectory.

[mathomp4]

@cmacmackin Do you know if this is now in FORD? (It is a ~3 year old issue and sometimes they fall through the cracks in closing)

As @ZedThree knows (thanks for 6.1.12!), I've been experimenting with FORD, and I've just today figured out the whole gh-pages and GitHub Action, etc. stuff to deploy the docs on push or whatever. But then my boss' next question was: "Can we version the documentation?"

I suppose I could, with clever enough GitHub Action bits, have the action run only on release, and use github.event.release.tag_name to deploy the pages to a folder with the new release tag, but as you say, having a nice dropdown to select between all the versions would be nice.

[cmacmackin]

No, this was never implemented. It's not actually a very easy thing to do. There is a sphinx plugin to do it there and basically it consists of a wrapper that will run sphinx on each tag in a git repository (subject to configurations) and then insert links in the sidebar of pages.

The way ford chooses filenames would make this difficult, as there is a possibility that a page's name would change between versions of code.

Anyway, that gives you an idea of what would be required. A PR would be given due consideration.