Handle .htaccess files when pushing to cantera.org and document contents

.github/workflows/main.yaml

@@ -107,7 +107,8 @@ jobs:
       run: |
         rsync -avzP --checksum --exclude='*.map' --exclude='*.md5' \
         --delete --delete-excluded --filter='P /mw_headers.git' --filter='P /documentation/dev/*' \
-        --filter='P /doc-versions.json' --filter='P /dev'
+        --filter='P /doc-versions.json' --filter='P /dev' --filter='P /stable'
+        --filter='P /robots.txt' --filter='P .htaccess' \
         "${WEBSITE_CLONE_DIR}/${NIKOLA_OUTPUT_DIR}/" ${RSYNC_USER}@${RSYNC_SERVER}:${RSYNC_DEST}
     - name: Upload the docs
       if: env.DEPLOY == 'true' && endsWith(github.ref, 'testing')
@@ -116,4 +117,6 @@ jobs:
       run: |
         rsync -avzP --checksum --exclude='*.map' --exclude='*.md5' \
         --delete --delete-excluded --filter='P /mw_headers.git' --filter='P /documentation/dev/*' \
+        --filter='P /doc-versions.json' --filter='P /dev' --filter='P /stable'
+        --filter='P /robots.txt' --filter='P .htaccess' \
         "${WEBSITE_CLONE_DIR}/${NIKOLA_OUTPUT_DIR}/" ${RSYNC_USER}@${RSYNC_SERVER}:${RSYNC_DEST}

README.md

@@ -53,3 +53,32 @@ site is built using the [Nikola](https://getnikola.com) static site generator.
   * `IC engine example </examples/python/reactors/ic_engine.py.html>`__
 * To link to a label in the YAML API docs:
   * :ref:`three-body <sec-yaml-three-body>`
+
+## Apache configuration
+To allow the version switcher to work smoothly between Cantera =< 3.0 and Cantera >= 3.1
+(where the directory structure changed significantly), we rely on several `mod_rewrite`
+rules, implemented in `.htaccess` files:
+
+* `/dev/.htaccess`:
+```conf
+RewriteBase "/dev/"
+
+RewriteRule "^cython/(.+)" "python/$1" [R]
+```
+
+* `/documentation/.htaccess`:
+```conf
+RewriteBase "/documentation/"
+
+RewriteRule "^dev/sphinx/html/cython/(.*)" "../dev/python/$1" [R]
+RewriteRule "^docs-3.0/sphinx/html/python/(.*)" "docs-3.0/sphinx/html/cython/$1" [R]
+RewriteRule "^dev/sphinx/html/(.+)"  "../dev/$1" [R]
+```
+
+* `/stable/.htaccess`:
+```conf
+RewriteBase "/stable/"
+
+RewriteRule "^cxx(.*)"  "../documentation/docs-3.0/doxygen/html/$1"
+RewriteRule "^(.*)"  "../documentation/docs-3.0/sphinx/html/$1"
+```