From c533ca90bbfe3846674adab216aaaf616b044f41 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Fri, 29 Sep 2023 19:56:26 -0400 Subject: [PATCH] [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 --- .github/workflows/main.yml | 14 +++++++------- doc/SConscript | 20 ++++++++++++-------- doc/doxygen/header.html | 4 ++-- doc/sphinx/_static/doc-versions.json | 2 +- doc/sphinx/conf.py | 6 +++--- doc/sphinx/reference.md | 2 +- 6 files changed, 26 insertions(+), 22 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 357f162ba..9131fa607 100644 --- 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() @@ -369,12 +369,12 @@ jobs: env: RSYNC_USER: "ctdeploy" RSYNC_SERVER: "cantera.org" - RSYNC_DEST: "cantera/documentation/dev" - DOCS_OUTPUT_DIR: "./build/doc/" + RSYNC_DEST: "cantera/dev" + DOCS_OUTPUT_DIR: "./build/doc/html/" run: | rsync -avzP --checksum --exclude='*.map' --exclude='*.md5' \ - --exclude='/doxygen/xml' --delete --delete-excluded \ - "${DOCS_OUTPUT_DIR}" ${RSYNC_USER}@${RSYNC_SERVER}:${RSYNC_DEST} + --delete --delete-excluded \ + "${DOCS_OUTPUT_DIR}" ${RSYNC_USER}@${RSYNC_SERVER}:${RSYNC_DEST} run-examples: name: Run Python ${{ matrix.python-version }} examples on ${{ matrix.os }} diff --git a/doc/SConscript b/doc/SConscript index 9e9121412..0b8d19fd4 100644 --- a/doc/SConscript +++ b/doc/SConscript @@ -96,17 +96,21 @@ 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): @@ -114,7 +118,7 @@ if localenv['sphinx_docs']: 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 index 0ed21f125..278a670d5 100644 --- a/doc/doxygen/header.html +++ b/doc/doxygen/header.html @@ -71,8 +71,8 @@ $extrastylesheet
diff --git a/doc/sphinx/_static/doc-versions.json b/doc/sphinx/_static/doc-versions.json index 6161c9919..a4e457ab4 100644 --- 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": "/dev/" }, { "name": "3.0.0 (stable)", diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py index 68200d623..99b4f4bdf 100644 --- a/doc/sphinx/conf.py +++ b/doc/sphinx/conf.py @@ -206,8 +206,8 @@ def setup(app): 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 @@ html_theme_options = { }, "primary_sidebar_end": ["numfocus"], "switcher": { - "json_url": "/documentation/dev/sphinx/html/_static/doc-versions.json", + "json_url": "/dev/_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 index c5e1ebf76..62afc25fc 100644 --- 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 ```