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

Convert website to Sphinx #263

Merged
merged 38 commits into from
Dec 18, 2024
Merged
Changes from 1 commit
Commits
Show all changes
38 commits
Select commit Hold shift + click to select a range
ce38ab6
Use Sphinx for building
bryanwweber Jun 17, 2022
96a65d1
Add sphinx-design extension for Bootstrap support
bryanwweber Jun 19, 2022
eb4a718
Update dependencies and instructions
bryanwweber Mar 18, 2023
804e5fd
Formatting
bryanwweber Mar 18, 2023
a38b3da
add python 3.9 support for type hints
bryanwweber Apr 5, 2023
50f0f38
Update pdm and dependencies
bryanwweber Jul 2, 2023
bf7b1c4
More or less reproduce the home page
bryanwweber Jul 2, 2023
40ca92e
Some content reformatting
bryanwweber Jul 3, 2023
97a40dc
Bump api-docs submodule
speth Feb 25, 2024
aacb13d
Add tool for copying API docs into place
speth Feb 26, 2024
97918cf
Add header links to versioned sections and make styling more consistent
speth Feb 26, 2024
af0f35c
Ignore pdm.lock file
speth Feb 26, 2024
6c701e5
Delete content that was migrated to the Cantera/cantera repo
speth Feb 26, 2024
a2f7053
Delete Nikola plugin and theme files
speth Feb 26, 2024
2663431
Improve formatting of cards on homepage
speth Feb 27, 2024
f84d11b
Convert "Community" page to Markdown and update formatting
speth Feb 28, 2024
22fecba
Convert "affiliated" page to Markdown and update formatting
speth Feb 28, 2024
3d56a5e
Convert "Governance" page to Markdown and update formatting
speth Feb 28, 2024
0e3887b
Convert Dave Goodwin memorial page to Markdown and update formatting
speth Feb 29, 2024
27c9bfb
Use ABlog to handle news posts
speth Feb 29, 2024
f7c57dc
Clean up formatting of all news posts
speth Mar 2, 2024
4b44a66
Fix some warnings and display issues on index and community pages
speth Mar 4, 2024
5bcdf55
Redirect search to stable docs on most pages
speth Mar 7, 2024
7463476
Match style of navbar icons in current docs
speth Mar 7, 2024
bed0d03
Fix header links to stable docs from subdirectories
speth Mar 7, 2024
31c7e2a
Remove unused local Sphinx extensions
speth Mar 7, 2024
cffb509
Use updated favicon
speth Mar 8, 2024
cd6fc33
Add "assets" directory needed for legacy doc landing pages
speth Mar 8, 2024
d28d656
[CI] Update CI for Sphinx-built site
speth Dec 11, 2024
b137e7f
Read intersphinx inventories from cantera.org
speth Dec 12, 2024
c67d727
Configure PDM as an "application"
speth Dec 12, 2024
d1f8c2e
Remove obsolete use of api-docs repository
speth Dec 13, 2024
8c3c9bb
Merge branch 'main' into website-reformat-sphinx-myst
speth Dec 14, 2024
836d872
Increase minimum Python version to 3.10
speth Dec 14, 2024
d23216a
Log more from pdm
speth Dec 14, 2024
4c1d386
Fix pdm configuration
speth Dec 14, 2024
ac6da52
Fix Sphinx config issues
speth Dec 16, 2024
3892bc4
Don't set a misleading version number
speth Dec 16, 2024
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
Prev Previous commit
Next Next commit
Formatting
  • Loading branch information
bryanwweber committed Mar 18, 2023
commit 804e5fd4a814659bf07605ae280892298fb3c1d6
2 changes: 1 addition & 1 deletion pages/science/reactors/constpresreactor.rst
Original file line number Diff line number Diff line change
@@ -92,4 +92,4 @@ for :math:`dm/dt`, the equation for each homogeneous phase species is:
\dot{m}_{k,gen} - Y_k \dot{m}_{wall}
\tag{3}

Equations 1-3 are the governing equations for a Constant Pressure Reactor.
Equations 1-3 are the governing equations for a Constant Pressure Reactor.
2 changes: 1 addition & 1 deletion pages/science/reactors/controlreactor.rst
Original file line number Diff line number Diff line change
@@ -97,4 +97,4 @@ for :math:`dm/dt`, the equation for each homogeneous phase species is:
\dot{m}_{k,gen} - Y_k \dot{m}_{wall}
\tag{4}

Equations 1-4 are the governing equations for a Control Volume Reactor.
Equations 1-4 are the governing equations for a Control Volume Reactor.
2 changes: 1 addition & 1 deletion pages/science/reactors/customreactor.rst
Original file line number Diff line number Diff line change
@@ -45,4 +45,4 @@ described in 7 steps:
A use case of a Custom Reactor where Cantera is used for evaluating
thermodynamic properties and kinetic rates while an external ODE solver
is used to integrate the resulting equations is linked here in the
`custom.py example </examples/python/reactors/custom.py.html>`__.
`custom.py example </examples/python/reactors/custom.py.html>`__.
2 changes: 1 addition & 1 deletion pages/science/reactors/cvodes.rst
Original file line number Diff line number Diff line change
@@ -294,4 +294,4 @@ Along with the rest of ``FuncEval``'s virtual functions, an appropriate override
the deprecated ``evalEqs()`` function, hence the deprecation warning. For more information see
Cantera's `reactor network science page </science/reactors/reactors.html>`__.

This documentation is based off @paulblum's `blog post <https://cantera.org/blog/gsoc-2020-blog-3.html>`__.
This documentation is based off @paulblum's `blog post <https://cantera.org/blog/gsoc-2020-blog-3.html>`__.
2 changes: 1 addition & 1 deletion pages/science/reactors/extensiblereactor.rst
Original file line number Diff line number Diff line change
@@ -163,4 +163,4 @@ that are able to be modified with ``before_``, ``after_``, or

More in-depth documentation on the different ways to modify equations using
an Extensible Reactor can be found `here <{{% ct_docs doxygen/html/de/d7e/classCantera_1_1ReactorDelegator.html %}}>`__ and `here
<{{% ct_docs sphinx/html/cython/zerodim.html#extensiblereactor %}}>`__.
<{{% ct_docs sphinx/html/cython/zerodim.html#extensiblereactor %}}>`__.
2 changes: 1 addition & 1 deletion pages/science/reactors/idealgasconstpresreactor.rst
Original file line number Diff line number Diff line change
@@ -88,4 +88,4 @@ for :math:`dm/dt`, the equation for each homogeneous phase species is:
\tag{3}

Equations 1-3 are the governing equations for an Ideal Gas Constant Pressure
Reactor.
Reactor.
2 changes: 1 addition & 1 deletion pages/science/reactors/idealgasreactor.rst
Original file line number Diff line number Diff line change
@@ -108,4 +108,4 @@ for :math:`dm/dt`, the equation for each homogeneous phase species is:
\dot{m}_{k,gen} - Y_k \dot{m}_{wall}
\tag{4}

Equations 1-4 are the governing equations for an Ideal Gas Reactor.
Equations 1-4 are the governing equations for an Ideal Gas Reactor.
2 changes: 1 addition & 1 deletion pages/science/reactors/pfr.rst
Original file line number Diff line number Diff line change
@@ -123,4 +123,4 @@ boundary condition for the next CSTR downstream.

An example for this procedure can be found in the `PFR example
</examples/python/reactors/pfr.py.html>`__ and the `surface PFR example
</examples/python/reactors/surf_pfr.py.html>`__.
</examples/python/reactors/surf_pfr.py.html>`__.
2 changes: 1 addition & 1 deletion pages/science/reactors/reactors.rst
Original file line number Diff line number Diff line change
@@ -519,4 +519,4 @@ conditions, you can run your simulation for a long time until the states are con
.. [1] Prior to Cantera 2.6, the sense of the net heat flow was reversed, with positive
:math:`\dot{Q}` representing heat removal from the system. However, the sense of heat
flow through a wall between two reactors was the same, with a positive value
representing heat flow from the left reactor to the right reactor.
representing heat flow from the left reactor to the right reactor.
2 changes: 1 addition & 1 deletion plugins/__init__.py
Original file line number Diff line number Diff line change
@@ -1 +1 @@
# Plugin modules go here.
# Plugin modules go here.
4 changes: 2 additions & 2 deletions plugins/bootstrap.py
Original file line number Diff line number Diff line change
@@ -25,9 +25,9 @@
THE SOFTWARE.
"""

from docutils import nodes, utils
import docutils
from docutils.parsers.rst import directives, Directive
from docutils import nodes, utils
from docutils.parsers.rst import Directive, directives
from nikola.plugin_categories import RestExtension


2 changes: 1 addition & 1 deletion plugins/copy_tree.py
Original file line number Diff line number Diff line change
@@ -7,9 +7,9 @@
faster. We prefer this plugin since we are copying folders around
for the API documentation.
"""
from shutil import copytree, ignore_patterns, rmtree
import os
from pathlib import Path
from shutil import copytree, ignore_patterns, rmtree

from nikola.plugin_categories import Task
from nikola.utils import config_changed
9 changes: 5 additions & 4 deletions plugins/new_release.py
Original file line number Diff line number Diff line change
@@ -12,13 +12,14 @@
"""

import re
from git import Repo
from nikola.plugin_categories import Command
import requests
from datetime import datetime
from pathlib import Path
from nikola import utils

import requests
from git import Repo
from lxml import etree, html
from nikola import utils
from nikola.plugin_categories import Command

CANTERA_WEBSITE = Path(__file__).parent.parent

2 changes: 1 addition & 1 deletion plugins/override_html_formatter.py
Original file line number Diff line number Diff line change
@@ -8,9 +8,9 @@
To create a codeblock to HTML formatter with nondefault options,
call pygments.formatters.HtmlFormatter([options])
"""
import nikola.utils
from nikola.plugin_categories import RestExtension
from pygments.formatters import HtmlFormatter
import nikola.utils


class OverrideHTMLFormatter(RestExtension):
16 changes: 11 additions & 5 deletions plugins/parse_docs.py
Original file line number Diff line number Diff line change
@@ -5,9 +5,10 @@
"""
from pathlib import Path

from lxml.html import parse, tostring
from nikola.plugin_categories import Task
from nikola.utils import get_logger
from lxml.html import tostring, parse


class ParseDocs(Task):
"""Parse the documentation to find link targets."""
@@ -63,15 +64,20 @@ def process_targets(dirname, base_dir, docs_folder):
parts = elem_id.split(".")
try:
# This pattern worked for the Cantera 2.5.1 docs
node = elem.xpath('code[contains(concat(" ", @class, " "), " descname ")]')
node = elem.xpath(
'code[contains(concat(" ", @class, " "), " descname ")]'
)
if not len(node):
# Output from Sphinx 4.4.0 seems to fit this pattern
node = elem.xpath('span[contains(concat(" ", @class, " "), " descname ")]')[0]
node = elem.xpath(
'span[contains(concat(" ", @class, " "), " descname ")]'
)[0]
title = node[0].text
except IndexError as err:
self.logger.error(
"Unknown title for class: {}\n{}".format(err,
tostring(elem))
"Unknown title for class: {}\n{}".format(
err, tostring(elem)
)
)
title = parts[-1]

23 changes: 12 additions & 11 deletions plugins/process_ref_targets.py
Original file line number Diff line number Diff line change
@@ -11,17 +11,17 @@
label. This information is stored in the ``site.ref_targets``
and ``site.anon_ref_targets` attributes.
"""
from nikola.plugin_categories import Task
from nikola.utils import get_logger, config_changed
from docutils.io import StringInput, StringOutput
from docutils import nodes
from docutils.readers.standalone import Reader
from docutils.core import Publisher
import tempfile
from copy import copy

from pathlib import Path
import tempfile

import requests
from docutils import nodes
from docutils.core import Publisher
from docutils.io import StringInput, StringOutput
from docutils.readers.standalone import Reader
from nikola.plugin_categories import Task
from nikola.utils import config_changed, get_logger

HERE = Path(__file__).parent

@@ -97,9 +97,10 @@ def tl_ch():
cantera_version = self.site.config["CANTERA_VERSION"]
yaml_rst_path = f"api-docs/docs-{cantera_version}/sphinx/html/_sources/yaml"
for rest_file in Path(yaml_rst_path).glob("**/*.rst.txt"):
stem = rest_file.name.split('.')[0]
permalink = (f"/documentation/docs-{cantera_version}"
f"/sphinx/html/yaml/{stem}.html"
stem = rest_file.name.split(".")[0]
permalink = (
f"/documentation/docs-{cantera_version}"
f"/sphinx/html/yaml/{stem}.html"
)
yield {
"basename": self.name,
3 changes: 1 addition & 2 deletions plugins/ref.py
Original file line number Diff line number Diff line change
@@ -7,9 +7,8 @@

from docutils import nodes
from docutils.parsers.rst import roles

from nikola.utils import split_explicit_title, get_logger
from nikola.plugin_categories import RestExtension
from nikola.utils import get_logger, split_explicit_title

LOGGER = get_logger("rest_ref")

54 changes: 30 additions & 24 deletions plugins/render_cxx_examples.py
Original file line number Diff line number Diff line change
@@ -8,15 +8,15 @@
as the key associated with the value that contains the string ``cxx``,
typically ``"../cantera/samples/cxx": "examples/cxx"``.
"""
import re
from itertools import chain
from pathlib import Path

from nikola.plugin_categories import Task
import natsort
from nikola import utils
from nikola.plugin_categories import Task
from pygments import highlight
from pygments.lexers import CppLexer
from itertools import chain
import re
import natsort


def render_example_index(site, kw, headers, output_file):
@@ -74,13 +74,15 @@ def render_example(site, kw, in_names, out_name):
code = highlight(
source_file.read_bytes(),
CppLexer(),
utils.NikolaPygmentsHTML(source_file.name)
utils.NikolaPygmentsHTML(source_file.name),
)
items.append(
{
"code": code,
"title": source_file.name,
"source_link": source_file.name,
}
)
items.append({
"code": code,
"title": source_file.name,
"source_link": source_file.name,
})

context = {
"items": items,
@@ -176,7 +178,6 @@ def gen_tasks(self):
uptodate["d"] = cxx_headings.keys()
uptodate["f"] = list(map(str, cxx_examples))


for subdir, cxx_ex_files in cxx_examples.items():
if not cxx_ex_files:
# Skip items that are not directories containing C++ files
@@ -186,30 +187,35 @@ def gen_tasks(self):
# Take the following comments, up to the next blank line
# (not including comment characters) as the summary.
doc = []

def append_doc(line):
line = line.lstrip('/* !')
if line.startswith('@file'):
line = re.sub(r'@file \w+.\w+\s*', '', line)
line = line.lstrip("/* !")
if line.startswith("@file"):
line = re.sub(r"@file \w+.\w+\s*", "", line)
doc.append(line)

for ex_file in cxx_ex_files:
if not ex_file.name.endswith('.cpp'):
if not ex_file.name.endswith(".cpp"):
continue
in_block_comment = False
for line in ex_file.read_text(encoding="utf-8").split("\n"):
line = line.strip()
if '*/' in line:
if "*/" in line:
in_block_comment = False
append_doc(line[:line.find('*/')])
elif line.startswith('/*'):
append_doc(line[: line.find("*/")])
elif line.startswith("/*"):
in_block_comment = True
append_doc(line)
elif in_block_comment or line.startswith("//") or line.startswith('* '):
elif (
in_block_comment
or line.startswith("//")
or line.startswith("* ")
):
append_doc(line)
elif any(doc):
break

title = ''
title = ""
summary = []
for line in doc:
if line and not title:
@@ -218,18 +224,18 @@ def append_doc(line):
summary.append(line)
elif summary:
break
summary = ' '.join(summary)
summary = " ".join(summary)
if not summary:
self.logger.warn(
f"The C++ example {ex_file!s} doesn't have an appropriate summary"
)
name = subdir.stem.replace('_', '-')
name = subdir.stem.replace("_", "-")

cxx_headings["examples"]["names"].append(name)
cxx_headings["examples"]["titles"][name] = title
cxx_headings["examples"]["summaries"][name] = summary
out_name = kw["output_folder"].joinpath(
self.examples_folder, name + '.html'
self.examples_folder, name + ".html"
)

yield {
@@ -262,7 +268,7 @@ def append_doc(line):
)

out_name = kw["output_folder"].joinpath(self.examples_folder, kw["index_file"])

all_files = [str(name[0]) for name in chain(cxx_examples.values()) if name]
yield {
"basename": self.name,
Loading