Migrate documentation hosting platform

[banesullivan]

Our documentation builds are getting rather large and hosting in a git-based system no longer makes sense. For context/posterity, we are currently hosting all of our documentation via GitHub Pages in https://github.com/pyvista/pyvista-docs

This has been coming for a while, but #4938 is a bit of a forcing function for this now since we are generating large files for the interactive scenes in the examples.

I'm opening this issue for transparency and to track the task of automating this though for now, I'm going to manually build/upload/deploy the docs to the new platform to get our docs published and stable.

I may disable the documentation build/publish GitHub Action during this process.

I'm currently looking into using Netlify as the hosting platform (and perhaps upgrading to a paid plan), but I would love any suggestions folks might have for alternate hosting platforms that will be flexible in the following ways:

1. We build our docs via GitHub Actions. Hard stop. We are not switching to a third party CI platform for building unless it can provide seriously compelling advantages (such as speeding up documentation builds by a factor of 3x)
2. This is tied to 1., but flexibility in how we upload. I find the Netlify CLI's netlify deploy --dir=. to be perfect
3. Large file sizes (10MB-100Mb) are okay and well handled
4. Reasonable bandwidth limits given the rising number of people viewing our documentation
5. If advertisements, only ethical ads.
6. ... Maybe some other things I'll uncover in this process?

Hosting platforms up for consideration so far:

1. Netlify
2. ReadTheDocs

[tkoyama010]

Having the documentation built on the service side in my mind is NOT a good idea in my mind. There is a risk of not being able to install certain apps on the service side, not supporting newer versions, etc. Therefore, I am +1 for the Netlify's artifact uploading feature.

That's why I want to remove ReadtheDocs as an option. ReadtheDocs is a great service for smaller projects and they have a nice and friendly community. But it is not our solution.

[akaszynski]

1. We build our docs via GitHub Actions. Hard stop. We are not switching to a third party CI platform for building unless it can provide seriously compelling advantages (such as speeding up documentation builds by a factor of 3x)

Fully agree with this. Staying within GitHub for build and hosting makes sense if it fulfills our needs. Hosting isn't possible anymore, but the builds should remain there.

The documentation build time is more of an issue of trying to do too much for each commit. Ideally we'd be able to do incremental builds. Barring that, I feel that waiting 90 minutes for CI checks really inhibits the development experience and we might consider an abbreviated build for PRs and run the full build on main and potentially on doc/* branches.

Having the documentation built on the service side in my mind is NOT a good idea... That's why I want to remove ReadtheDocs as an option.

Also agree. It's great for small projects, but not for larger ones where you need full control of the build.

[tkoyama010]

The documentation build time is more of an issue of trying to do too much for each commit. Ideally we'd be able to do incremental builds. Barring that, I feel that waiting 90 minutes for CI checks really inhibits the development experience and we might consider an abbreviated build for PRs and run the full build on main and potentially on doc/* branches.

Let's discuss this in the new issue.

[banesullivan]

Update: I've gotten this working (quite elegantly) with Netlify and will be working to automate the deployments in #5360

For now, I will manually handle any documentation deployments. Once I'm wrapped up, I will summarize the structure and any knowldege needed for maintaining this, but so far:

• I have moved our previous GitHub Pages documentation builds to https://github.com/pyvista/pyvista-docs-archive. This repository will be archived once the dust settles.
• Our main site is managed in https://github.com/pyvista/pyvista-docs now
• Check out https://github.com/pyvista/pyvista-docs/blob/main/netlify.toml to see how I manage the proxies for each version. Technically, each published version of the docs are their own standalone site which get proxied through the /version/MAJOR.MINOR path on the main site.
• This is all configured under my personal Netlify account because its free that way