[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 1, 2023 · 5932eed · 5932eed
1 parent 2b254d7
commit 5932eed
Show file tree

Hide file tree

Showing 5 changed files with 22 additions and 18 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/conf.py b/doc/sphinx/conf.py
@@ -208,8 +208,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 = {

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