This repository contains the source code for the cantera.org website. The site is built using the Nikola static site generator.
- Create a virtual environment for Nikola (i.e., using conda or virtualenv)
- Clone the Cantera source:
git clone https://github.com/Cantera/cantera.git
- Clone the Cantera Jupyter examples:
git clone https://github.com/Cantera/cantera-jupyter.git
- Clone the Cantera website source:
git clone https://github.com/Cantera/cantera-website.git
- Enter the website repo:
cd cantera-website
- Copy the current development documentation:
curl -O https://cantera.org/documentation/dev/dev-docs.tar.bz2
- Extract the dev docs:
tar jxf dev-docs.tar.bz2 --strip-components=1 -C api-docs/dev
- Inside the website repo, install the required packages:
pip install -r requirements.txt
- Build the website and open in browser:
nikola auto -b
or usenikola serve -p 9000 -b
for different port
- Copy one of the existing
render_*_examples.py
andrender_*_examples.plugin
- Add the source folder as the key and destination folder to the
EXAMPLES_FOLDERS
dictionary inconf.py
- Edit the
render_*_examples.py
file to build the examples - See this blog post for more information about building Nikola tasks
- New example categories are stored in folders in the Jupyter and Python example repositories
- If new categories (folders) are added to the examples, the appropriate renderer needs to be updated
- In the Jupyter and Python examples, there's a dictionary called
*_headers
. Each folder of examples has a key in that dictionary. The values are a nested dictionary with three keys:name
: The name used on the index page for that categoryfiles
: An empty list that gets filled with the names of the examples in this categorysummaries
: A empty dictionary that gets filled with keys that are the example filename and values that are the summary from that example
- Add a new key to that dictionary with the folder name as the key and fill in the
name
key in the nested dictionary and set thefiles
andsummaries
keys to the empty list and empty dictionary, respectively
- To add the latest version's release notes:
nikola new_release
- To add release notes for a version by its tag name:
nikola new_release -t {tag_name}
- Example:
nikola new_release -t v2.4.0
- Example:
- To add release notes for a version by its release ID:
nikola new_release -i {id}
- Example:
nikola new_release -i 12508904
- Example:
- To link to another section on the same page (using the title of the section):
Governing Equations for Single Reactors
_ - To link to an external site:
YAML 1.2 <https://yaml.org/spec/1.2/spec.html>
__
- To link to a Python class:
- :py:class:
ConstPressureReactor
- :py:class:
- To link to a C++ class:
ThermoPhase <{{% ct_docs doxygen/html/dc/d38/classCantera_1_1ThermoPhase.html %}}>
__
- To link to an example:
IC engine example </examples/python/reactors/ic_engine.py.html>
__
- To link to a label in the YAML API docs:
- :ref:
three-body <sec-yaml-three-body>
- :ref:
To allow the version switcher to work smoothly between Cantera =< 3.0 and Cantera >= 3.1
(where the directory structure changed significantly), we rely on several mod_rewrite
rules, implemented in .htaccess
files:
/dev/.htaccess
:
RewriteBase "/dev/"
RewriteRule "^cython/(.+)" "python/$1" [R]
/documentation/.htaccess
:
RewriteBase "/documentation/"
RewriteRule "^dev/sphinx/html/cython/(.*)" "../dev/python/$1" [R]
RewriteRule "^docs-3.0/sphinx/html/python/(.*)" "docs-3.0/sphinx/html/cython/$1" [R]
RewriteRule "^dev/sphinx/html/(.+)" "../dev/$1" [R]
/stable/.htaccess
:
RewriteBase "/stable/"
RewriteRule "^cxx(.*)" "../documentation/docs-3.0/doxygen/html/$1"
RewriteRule "^(.*)" "../documentation/docs-3.0/sphinx/html/$1"