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"
+```