Make available the documentation of older releases

[jhlegarreta]

Documentation of older releases should be kept available on the website. Ideally, the latest/current commit could be displayed, but users should be able to choose and look up the documentation of older releases.

I know that the documentation of older releases is available at https://itk.org/download/, but I think users rarely download a documentation ZIP file to look at the corresponding documentation/the above would be appreciated.

Also, right now it is unclear that the online documentation refers to the latest/current commit (and not the displayed tag) unless one realizes about the build date at the bottom. This also happens with the stable documentation linked from itk.org
https://itk.org/Doxygen/html/index.html

[thewtex]

We can use the same system as Slicer: (h/t @jcfr):

https://github.com/Slicer/apidocs.slicer.org/tree/gh-pages

[jcfr]

A possible path forward:

• Add each releases (5.2, 5.4, master, ...) a directory in the gh-pages branch
• Add an index.html page dynamically retrieving the available directories. See this page for an examle
• Ensure commits are always squashed. This is important to avoid growing the size of the repo beyond GitHub limits and allow it to be efficiently downloaded
• Add a scheduled GitHub Actions workflow that will:
  1. Checkout the gh-pages of this repository using action/checkout and with path: "ITKDoxygen-gh-pages"
  2. Checkout the latest ITK master using action/checkout specifying the ITK GitHub repo with `path: "ITK-master"``
  3. Use the docker image to build the documentation
  4. Copy the relevant directory into master directory
  5. Force push using an action like push-git-subdirectory-as-branch by specifying SQUASH_HISTORY to true

Existing documentation archives could also be added as release assets to a release called Archives created using https://gist.github.com/jcfr/9c0c0133c2d3fa2b029e6dd2648f7720

[thewtex]

We should be able to have old releases deployed to GitHub Pages, keep the repository light, by

• Uploading old artifacts to GitHub Releases (note: there is WIP to also upload to GH Releases in Adding GHA suppor to publish to GH releases #2)
• Create an equilvalent consolidate-documentation step, that downloads and index of existing releases, the current nightly build
  • Note: GitHub Pages has a 10 GB deployment limit, which is not sufficient for all the older releases. Each older release should be deployed separately, e.g. on an IPFS CDN, and linked to with an index page.
• Deploy with the new actions/deploy-pages

[thewtex]

All the versions are now published on ReadTheDocs: https://docs.itk.org/projects/doxygen/

[jhlegarreta]

Thank you @thewtex. Apologies for not having been able to review your PRs on time. Hats off to this tremendous work 💯.