[Doc] Flatten output directory structure

Copy Doxygen output into a subdirectory of Sphinx so the Sphinx index can be the full site index. Partially addresses Cantera/cantera-website#229
speth · Oct 3, 2023 · 3553f5d · 3553f5d
1 parent 6ec0c19
commit 3553f5d
Show file tree

Hide file tree

Showing 6 changed files with 24 additions and 20 deletions.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -345,13 +345,13 @@ jobs:
           mv config-options-dev.rst build/doc/scons/
       - name: Create archive for docs output
         run: |
-          cd build
-          tar -czf docs.tar.gz doc
+          cd build/doc
+          tar --exclude="*.map" --exclude="*.md5" -czf docs.tar.gz html
         if: failure() || success()
       - name: Store archive of docs output
         uses: actions/upload-artifact@v3
         with:
-          path: build/docs.tar.gz
+          path: build/doc/docs.tar.gz
           name: docs
           retention-days: 14
         if: failure() || success()
@@ -370,10 +370,10 @@ jobs:
           RSYNC_USER: "ctdeploy"
           RSYNC_SERVER: "cantera.org"
           RSYNC_DEST: "cantera/documentation/dev"
-          DOCS_OUTPUT_DIR: "./build/doc/"
+          DOCS_OUTPUT_DIR: "./build/doc/html"
         run: |
           rsync -avzP --checksum --exclude='*.map' --exclude='*.md5' \
-          --exclude='/doxygen/xml' --delete --delete-excluded \
+          --delete --delete-excluded \
           "${DOCS_OUTPUT_DIR}" ${RSYNC_USER}@${RSYNC_SERVER}:${RSYNC_DEST}
 
   run-examples:

diff --git a/doc/SConscript b/doc/SConscript
@@ -96,25 +96,29 @@ def get_function_name(function_string):
     else:
         return sig
 
-if localenv['doxygen_docs']:
-    docs = build(localenv.Command('#build/doc/doxygen/html/index.html',
-                                  'doxygen/Doxyfile', 'doxygen $SOURCE'))
+if localenv['doxygen_docs'] or localenv['sphinx_docs']:
+    docs = build(localenv.Command(
+        '#build/doc/html/cxx/index.html', 'doxygen/Doxyfile',
+        [
+            Delete("build/doc/html/cxx"),
+            'doxygen $SOURCE',
+            Copy("build/doc/html/cxx", "build/doc/doxygen/html")
+        ]
+    ))
     env.Depends(docs, env.Glob('#doc/doxygen/*') +
                       multi_glob(env, '#include/cantera', 'h') +
                       multi_glob(env, '#include/cantera/*', 'h') +
                       multi_glob(env, '#src/cantera/*', 'h', 'cpp'))
 
     env.Alias('doxygen', docs)
-    install(localenv.RecursiveInstall, '$inst_docdir/doxygen/html',
-            '#/build/doc/doxygen/html', exclude=['\\.map', '\\.md5'])
 
 if localenv['sphinx_docs']:
     def build_sphinx(target, source, env):
         cmd = [env['sphinx_cmd']] + env['sphinx_options'].split()
         if env['logging'] == 'debug':
             cmd.append('-v')
         cmd += ('-b', 'html', '-d', 'build/doc/sphinx/doctrees', 'build/doc/sphinx',
-                'build/doc/sphinx/html')
+                'build/doc/html')
         code = subprocess.call(cmd, env=env['ENV'])
         if code:
             raise Errors.BuildError(target, action=env['sphinx_cmd'])
@@ -251,5 +255,5 @@ if localenv['sphinx_docs']:
     localenv.AlwaysBuild(sphinxdocs)
     if localenv['doxygen_docs']:
         localenv.Depends(sphinxdocs, docs)
-    install(localenv.RecursiveInstall, '$inst_docdir/sphinx/html',
-            '#build/doc/sphinx/html')
+    install(localenv.RecursiveInstall, '$inst_docdir/html',
+            '#build/doc/html', exclude=['\\.map', '\\.md5'])
diff --git a/doc/doxygen/header.html b/doc/doxygen/header.html
@@ -71,8 +71,8 @@
 </div>
 <div>
   <ul class="sm sm-dox" style="display: block;">
-    <li><a id="selected" href="$relpath^../../sphinx/html/reference.html">Reference</a></li>
-    <li><a href="$relpath^../../sphinx/html/examples.html">Examples</a></li>
+    <li><a id="selected" href="$relpath^../reference.html">Reference</a></li>
+    <li><a href="$relpath^../examples.html">Examples</a></li>
   </ul>
 </div>
 <!--END TITLEAREA-->

diff --git a/doc/sphinx/_static/doc-versions.json b/doc/sphinx/_static/doc-versions.json
@@ -2,7 +2,7 @@
     {
         "name": "3.1 (dev)",
         "version": "3.1",
-        "url": "/documentation/dev/sphinx/html/"
+        "url": "/v3.1/"
     },
     {
         "name": "3.0.0 (stable)",

diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py
@@ -206,8 +206,8 @@ def escape_splats(app, what, name, obj, options, lines):
 autoclass_content = 'both'
 
 doxylink = {
-    'ct': (os.path.abspath('../../doc/Cantera.tag'),
-            '../../doxygen/html/')
+    'ct': (os.path.abspath('../Cantera.tag'),
+           'cxx/')
 }
 
 intersphinx_mapping = {
@@ -305,7 +305,7 @@ def escape_splats(app, what, name, obj, options, lines):
     },
     "primary_sidebar_end": ["numfocus"],
     "switcher": {
-        "json_url": "/documentation/dev/sphinx/html/_static/doc-versions.json",
+        "json_url": "/_static/doc-versions.json",
         # "json_url": "https://cantera.org/doc-versions.json",
         "version_match": version,
     },

diff --git a/doc/sphinx/reference.md b/doc/sphinx/reference.md
@@ -31,7 +31,7 @@ mechanism files.
 ```
 
 ```{grid-item-card} C++ API Reference
-:link: ../../doxygen/html/index.html
+:link: cxx/index.html
 :text-align: center
 ```