Improve HTML Download of Documentation (#4146)

.readthedocs.yml

@@ -12,7 +12,6 @@ sphinx:
 # Optionally build your docs in additional formats such as PDF
 formats:
   - pdf
-   - htmlzip
 
 # Optionally set the version of Python and requirements required to build your docs
 python:
@@ -25,6 +24,17 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3"  # latest stable cpython version
+  jobs:
+    post_build:
+      # Based on https://github.com/readthedocs/readthedocs.org/issues/3242#issuecomment-1410321534
+      # This provides a HTML zip file for download, with the same structure as the hosted website
+      - mkdir --parents $READTHEDOCS_OUTPUT/htmlzip
+      - cp --recursive $READTHEDOCS_OUTPUT/html $READTHEDOCS_OUTPUT/$READTHEDOCS_PROJECT
+      # Hide the "other versions" dropdown. This is a workaround for those versions being shown,
+      # but not being accessible, as they are not built. Also, they hide the actual sidebar menu
+      # that is relevant only on ReadTheDocs.
+      - echo "#furo-readthedocs-versions{display:none}" >> $READTHEDOCS_OUTPUT/$READTHEDOCS_PROJECT/_static/styles/furo-extensions.css
+      - cd $READTHEDOCS_OUTPUT ; zip --recurse-path --symlinks htmlzip/$READTHEDOCS_PROJECT.zip $READTHEDOCS_PROJECT
 
 search:
   ranking: # bump up rank of commonly searched pages: (default: 0, values range from -10 to 10)