Improve Documentation Generation and Versioning #338
Description
this is derived from my attempt to address #327
Our current use of sphinx-multiversion for documentation generation presents several issues. This approach significantly bloats the docs directory within our main codebase, making the repository larger and harder to manage.
A more substantial problem arises from sphinx-multiversion's method of attempting to build documentation for old code using the same Python environment. This setup is prone to failure, as evolving project dependencies or Python version requirements can easily break the build process for past releases. Maintaining consistent build compatibility across all historical versions within a single environment is unsustainable.
To resolve these issues, I propose transitioning to a "build-once, stay-forever" documentation strategy. With this approach, documentation for each version will be built only once upon its release, generating entirely static HTML files.
This change will also allow us to store all generated documentation, including older versions, in a separate, dedicated documentation hub repository. This separation will declutter our main project repository and ensure that historical documentation remains stable, accurate, and accessible, free from the complications of future environmental or dependency changes. This new strategy aims to create a more robust and maintainable documentation pipeline.