Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Website structure update #1631

Merged
merged 22 commits into from
Oct 9, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
05fb0c3
Modify Doxygen navbar to link to Sphinx docs
speth Sep 29, 2023
40b5f58
Enable MyST usage in Sphinx
speth Sep 29, 2023
3d94cdb
Reformat "Reference" landing page
speth Sep 29, 2023
fa8e26f
Remove previous/next page links from Sphinx docs
speth Sep 29, 2023
594b46b
[Doc] Create structure for "science" docs
speth Sep 29, 2023
55985bd
[Doc] Flatten output directory structure
speth Sep 29, 2023
09affe1
[Doc] Use 'python' instead of 'cython' for filenames and refs
speth Sep 30, 2023
2252c34
[Doc] Create skeleton for revised layout
speth Sep 30, 2023
1699712
[Doc] Fix syntax error in cantera.bib
speth Sep 30, 2023
ea21677
[Doc] Add bibliography to Sphinx docs
speth Sep 30, 2023
969215e
Add Python tutorial as a MyST notebook
speth Sep 30, 2023
89f6507
[Doc] Update to pydata-sphinx-theme 0.14 and fix some styling issues
speth Oct 2, 2023
6c5da31
[Doc] Reorganize Sphinx index pages and convert to MyST
speth Oct 3, 2023
05cbae4
[Doc] Add admonitions redirecting users to stable docs
speth Oct 3, 2023
ae72ef9
Set favicon for Sphinx and Doxygen docs
speth Oct 3, 2023
4ad1422
Use higher-res icon in Doxygen title area
speth Oct 3, 2023
c82971b
[Doc] Add more stub pages to the Sphinx docs
speth Oct 3, 2023
aca2be9
Migrate compilation docs into Sphinx/MyST
speth Oct 4, 2023
8cb31af
Enable sphinx-copybutton extension
speth Oct 6, 2023
6039c55
[Doc] Simplify addition of "Community" link
speth Oct 8, 2023
10dcff2
[Doc] Avoid needing two lines for header links
speth Oct 8, 2023
ba90868
[Doc] Use cards for Examples landing page
speth Oct 9, 2023
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 11 additions & 16 deletions .github/workflows/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -323,10 +323,10 @@ jobs:
run: python3 -m pip install -U pip setuptools wheel
- name: Install Python dependencies
run: |
python3 -m pip install ruamel.yaml scons numpy cython sphinx==6.2.1 \
sphinxcontrib-matlabdomain sphinxcontrib-doxylink pint \
pydata-sphinx-theme==0.13.3 sphinx-argparse sphinx_design matplotlib \
pandas scipy
python3 -m pip install ruamel.yaml scons numpy cython 'sphinx>=5.3.0' \
sphinxcontrib-matlabdomain sphinxcontrib-doxylink sphinxcontrib-bibtex \
pydata-sphinx-theme==0.14.1 sphinx-argparse sphinx_design myst-nb \
sphinx-copybutton matplotlib pandas scipy pint
python3 -m pip install "git+https://github.com/sphinx-gallery/sphinx-gallery.git@master"
python3 -m pip install "git+https://github.com/Cantera/sphinx-tags.git@main"
- name: Build Cantera
Expand All @@ -338,20 +338,15 @@ jobs:
python3 `which scons` help --options
python3 `which scons` help --list-options
python3 `which scons` help --option=prefix
- name: Parse configuration options from SConstruct as reST
run: |
python3 `which scons` help --restructured-text --dev --output=config-options-dev.rst
mkdir build/doc/scons
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()
Expand All @@ -369,12 +364,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 --filter='P .htaccess' \
"${DOCS_OUTPUT_DIR}" ${RSYNC_USER}@${RSYNC_SERVER}:${RSYNC_DEST}

run-examples:
name: Run Python ${{ matrix.python-version }} examples on ${{ matrix.os }}
Expand Down
5 changes: 5 additions & 0 deletions SConstruct
Original file line number Diff line number Diff line change
Expand Up @@ -937,6 +937,11 @@ for arg in ARGUMENTS:
logger.error(f"Encountered unexpected command line option: {arg!r}")
sys.exit(1)

# Store full config for doc build
if env['sphinx_docs']:
config.add(windows_options)
env['config'] = config

env["cantera_version"] = "3.1.0a1"
# For use where pre-release tags are not permitted (MSI, sonames)
env['cantera_pure_version'] = re.match(r'(\d+\.\d+\.\d+)', env['cantera_version']).group(0)
Expand Down
32 changes: 24 additions & 8 deletions doc/SConscript
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@

from collections import namedtuple
from os.path import join as pjoin
from pathlib import Path
import os
import subprocess
from buildutils import *
Expand Down Expand Up @@ -96,25 +97,30 @@ 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']:
localenv.PrependENVPath('PYTHONPATH', Dir('#build/python').abspath)
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'])
Expand Down Expand Up @@ -157,6 +163,16 @@ if localenv['sphinx_docs']:
localenv.Command(f"#build/doc/samples/clib/{clib_file.name}",
clib_file, Copy("$TARGET", "$SOURCE")))

# Generate documentation for SCons configuration options
def save_config(target, source, env):
Path(str(target[0])).parent.mkdir(parents=True, exist_ok=True)
with open(str(target[0]), "w") as outfile:
outfile.write(env["config"].to_rest())
scons_opts = localenv.Command(
"#build/doc/sphinx/develop/compiling/scons-config-options.rst.inc",
"#SConstruct", save_config)
env.Depends(sphinxdocs, scons_opts)

# Create a list of MATLAB classes to document. This uses the NamedTuple
# structure defined at the top of the file. The @Data and @Utilities
# classes are fake classes for the purposes of documentation only. Each
Expand Down Expand Up @@ -251,5 +267,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'])
3 changes: 2 additions & 1 deletion doc/doxygen/Doxyfile
Original file line number Diff line number Diff line change
Expand Up @@ -1213,7 +1213,8 @@ HTML_STYLESHEET =
# list). For an example see the documentation.
# This tag requires that the tag GENERATE_HTML is set to YES.

HTML_EXTRA_STYLESHEET = ext/doxygen-awesome-css/doxygen-awesome.css
HTML_EXTRA_STYLESHEET = ext/doxygen-awesome-css/doxygen-awesome.css \
doc/doxygen/cantera-doxygen.css

# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
# other source files which should be copied to the HTML output directory. Note
Expand Down
39 changes: 39 additions & 0 deletions doc/doxygen/cantera-doxygen.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
/* Colors to match pydata-sphinx-theme */
html {
--primary-color: rgb(10, 125, 145);
--pst-color-text-muted: rgb(100, 100, 100);
}

html.dark-mode {
--primary-color: rgb(63, 177, 197);
--pst-color-text-muted: rgb(164, 164, 164);
}

ul#main-menu li a {
/* Hide Doxygen navigation tabs that are duplicated in the sidebar */
visibility: hidden;
display: none !important;
}

div#top {
/* Fix alignment of nav tabs added using header.html */
justify-content: left;
}

/* Re-style the nav bar links to approximate pydata-sphinx-theme */
.sm-dox a {
color: var(--pst-color-text-muted) !important;
font-size: 16px;
padding: 0 8px;
}

.sm-dox a#selected {
color: var(--primary-color) !important;
font-weight: bold;
}

.sm-dox a:hover {
background: unset;
color: var(--primary-color) !important;
font-size: 16px;
}
10 changes: 8 additions & 2 deletions doc/doxygen/cantera.bib
Original file line number Diff line number Diff line change
Expand Up @@ -364,8 +364,7 @@ @article{sengers1986
volume = {15},
url = {https://dx.doi.org/10.1063/1.555763},
year = {1986},
%doi = {10.1063/1.555763},
}
doi = {10.1063/1.555763}}
@article{silvester1977,
author = {L.~F.~Silvester and K.~S.~Pitzer},
title = {Thermodynamics of electrolytes. 8. High-temperature properties, including
Expand All @@ -383,6 +382,13 @@ @book{smith1982
isbn = {978-0471093473},
title = {Chemical Reaction Equilibrium Analysis: Theory and Algorithms},
year = {1982}}
@online{smith1999,
title = {{GRI-Mech} 3.0},
author = {G.~P.~Smith and D.~M.~Golden and M.~Frenklach and N~.W.~Moriarty and
B.~Eiteneer and M.~Goldenberg and C.~T.~Bowman and R.~K.~Hanson and S.~Song
and W.~C.~Gardiner, Jr. and V.~V.~Lissianski and Z.~Qin},
url = {http://combustion.berkeley.edu/gri-mech/version30/text30.html},
year = {1999}}
@article{stewart1989,
author = {P.~H.~Stewart and C.~W.~Larson and D.~Golden},
journal = {Combustion and Flame},
Expand Down
11 changes: 11 additions & 0 deletions doc/doxygen/header.html
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
<link rel="shortcut icon" href="$relpath^../_static/images/favicon.png">
<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="$relpath^jquery.js"></script>
<script type="text/javascript" src="$relpath^dynsections.js"></script>
Expand Down Expand Up @@ -69,5 +70,15 @@
</tbody>
</table>
</div>
<div>
<ul class="sm sm-dox" style="display: block;">
<li><a href="$relpath^../install/index.html">Install</a></li>
<li><a href="$relpath^../userguide/index.html">User Guide</a></li>
<li><a href="$relpath^../examples/index.html">Examples</a></li>
<li><a id="selected" href="$relpath^../reference/index.html">Reference</a></li>
<li><a href="$relpath^../develop/index.html">Develop</a></li>
<li><a href="/community.html">Community</a></li>
</ul>
</div>
<!--END TITLEAREA-->
<!-- end header part -->
24 changes: 24 additions & 0 deletions doc/sphinx/_static/custom.css
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
html {
--pst-icon-external-link: "";
}

p + div.math {
/* Remove post-paragraph space ahead of equation to center vertically */
margin-top: -1.15em;
Expand All @@ -8,3 +12,23 @@ p + div.math {
display: none;
visibility: hidden;
}

/* Make extra room for header section links when page isn't wide enough */
@media(max-width: 1199.88px) {
/* Collapse search field to just a button */
button.search-button-field .search-button__default-text {
display: none;
visibility: hidden;
}
.search-button-field > :not(svg) {
display: none;
visibility: hidden;
}

/* Hide text portion of the Cantera logo */
.navbar-brand img {
width: 36px;
object-fit: cover;
object-position: left
}
}
2 changes: 1 addition & 1 deletion doc/sphinx/_static/doc-versions.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
{
"name": "3.1 (dev)",
"version": "3.1",
"url": "/documentation/dev/sphinx/html/"
"url": "/dev/"
},
{
"name": "3.0.0 (stable)",
Expand Down
Binary file modified doc/sphinx/_static/images/cantera-icon.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added doc/sphinx/_static/images/favicon.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
31 changes: 0 additions & 31 deletions doc/sphinx/_templates/cantera-org-links.html

This file was deleted.

4 changes: 3 additions & 1 deletion doc/sphinx/_templates/numfocus.html
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
<div id="numfocus">
<a href="https://numfocus.salsalabs.org/donate-to-cantera/index.html" class="btn btn-secondary" type="button">Donate to Cantera</a>
<a href="https://numfocus.salsalabs.org/donate-to-cantera/index.html"
class="sd-sphinx-override sd-btn sd-text-wrap sd-btn-secondary reference external"
type="button">Donate to Cantera</a>
<a href="https://numfocus.org/"><img src="{{pathto("_static/images/powered_by_NumFOCUS.svg", 1) }}" border="0" alt="NumFOCUS"/></a>
</div>
Loading
Loading