🔧 Set up versioned documentation

Fixes

Fixes #223 by @shnizzedy

Description

Consolidates the build process. Before this PR, docs/developer and docs/user are built separately. After, docs is built all at once.
Supports multiple versions of documentation with the version between docs/ and (/developer or /user). The version is tagged with the GitHub release tag of C-PAC, plus a copy of the latest tag in latest and the develop branch of C-PAC in nightly.
A dropdown is added to the top and bottom of the page that allows visitors to switch between versions.
A custom 404 page is added that redirects old URLs to the latest build. If no latest version of that page exists, the 404 displays.

Technical details

CircleCI still runs Sphinx to build the docs. A push to source after this PR is merged will build to nightly in the branch master. A push to build-version will build to the tag in build_version.txt. These instructions are spelled out in CONTRIBUTING in this PR.
I already pushed with https://github.com/FCP-INDI/fcp-indi.github.com/blob/8c6105da43d2e41f4d71a36e8cd9233460d2edbc/build_version.txt#L1 to generate a gh-pages branch containing these versions: https://github.com/FCP-INDI/fcp-indi.github.com/blob/915c31a0eba64d37ef79409444a41e09c6249825/docs/versions.txt#L1-L2. A push to build-version with a different tag in build_version.txt will build that version of C-PAC's docs to master.
GitHub requires organization pages to build from master. If this PR is merged into source, the current gh-pages branch should be merged onto master first.
In a couple places, I hardcoded the base URL. This code is obviously not ideal, but the instances are few enough that I opted for expediency in these instances. https://github.com/FCP-INDI/fcp-indi.github.com/blob/a227a0e6d86e8af7759bbdef0c35d9174de3d4f5/404.html#L34 https://github.com/FCP-INDI/fcp-indi.github.com/blob/a227a0e6d86e8af7759bbdef0c35d9174de3d4f5/scripts/versionList.js#L5

Tests

A fork is running at https://shnizzedy.github.io/fcp-indi.github.com/docs with the only differences being the hardcoded urls are set to shnizzedy.github.io/fcp-indi.github.com instead of fcp-indi.github.io

Screenshots

screenshot of dropdowns screenshot of 404 page

Additional details

Autodoc images

The autodoc generated images are off by one directory level after this change. As far as I can tell, only a few of those are working right now anyway, and they're all in the developer section.

Examples

Before & after (after image is looking at https://shnizzedy.github.io/fcp-indi.github.com/docs/v1.6.2a/developer/workflows/developer/images/generated/motion_statistics.png but the image is at https://shnizzedy.github.io/fcp-indi.github.com/docs/v1.6.2a/developer/workflows/images/generated/motion_statistics.png)
Before & after

Reviewing this PR

@sgiavasis, @HechengJin0, @SucyLi, @anibalsolon, please take a moment to check a few pages at https://shnizzedy.github.io/fcp-indi.github.com/docs. The biggest opportunity for an issue to arise from these changes that I can see is missing updating some relative paths. I think I got them all (besides the ones autogenerated from docstrings as mentioned above), but more eyes would be great.

Future deployments

With these changes, we can pretty easily set up the CI for C-PAC to automatically build version documents on each new release and nightly documents on each merge into develop.

Checklist

[x] My pull request has a descriptive title (not a vague title like Update index.md).
[x] My pull request targets the source branch of the repository.
[x] My commit messages follow best practices.
[x] My code follows the established code style of the repository.
[x] I added tests for the changes I made (if applicable).
[ ] I updated the changelog.
[x] I added or updated documentation (if applicable).
[x] I tried running the project locally and verified that there are no visible errors.

Developer Certificate of Origin

``` Developer Certificate of Origin Version 1.1 Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 1 Letterman Drive Suite D4700 San Francisco, CA, 94129 Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Developer's Certificate of Origin 1.1 By making a contribution to this project, I certify that: (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it. (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. ```

FCP-INDI / fcp-indi.github.io