From d3811cca4f5e46f212c3fb1771712eaa563aaa6c Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Sun, 16 Jan 2022 18:41:16 -0500 Subject: [PATCH 1/7] Use nicer titles/summaries for Jupyter examples This uses the following content from the first Markdown block: - The title is taken from the first heading (starting with '#') - The short description on the index page is the first non-heading paragraph (separated from other paragraphs following paragraphs by one or more blank lines) --- plugins/render_jupyter_examples.py | 29 +++++++++++++++---- .../templates/jupyter-example-index.tmpl | 2 +- 2 files changed, 25 insertions(+), 6 deletions(-) diff --git a/plugins/render_jupyter_examples.py b/plugins/render_jupyter_examples.py index b7b17aa54..fe517aea4 100644 --- a/plugins/render_jupyter_examples.py +++ b/plugins/render_jupyter_examples.py @@ -169,10 +169,10 @@ def gen_tasks(self): "jupyter-example-index.tmpl" ) jupyter_headers = OrderedDict( - thermo=dict(name="Thermodynamics", files=[], summaries={}), - reactors=dict(name="Reactor Networks", files=[], summaries={}), - flames=dict(name="One-Dimensional Flames", files=[], summaries={}), - electrochemistry=dict(name="Electrochemistry", files=[], summaries={}), + thermo=dict(name="Thermodynamics", files=[], summaries={}, titles={}), + reactors=dict(name="Reactor Networks", files=[], summaries={}, titles={}), + flames=dict(name="One-Dimensional Flames", files=[], summaries={}, titles={}), + electrochemistry=dict(name="Electrochemistry", files=[], summaries={}, titles={}), ) def get_b64_str(parent, img_fname): @@ -201,11 +201,20 @@ def get_b64_str(parent, img_fname): jupyter_headers[ex_category]["files"].append(jpy_ex_file) data = json.loads(jpy_ex_file.read_text(encoding="utf-8")) doc = "" + title = "" for cell in data["cells"]: if cell["cell_type"] != "markdown": continue if not doc: - doc = cell["source"][0].replace("#", "").strip() + doc = [] + for line in cell["source"]: + if doc and title and not line.strip(): + break + if not title and line.startswith("#"): + title = line.replace("#", "").strip() + else: + doc.append(line.strip()) + doc = " ".join(doc) for img_idx, cell_src in enumerate(cell["source"]): if "img" in cell_src: img = lxml.html.fromstring(cell_src) @@ -245,6 +254,16 @@ def get_b64_str(parent, img_fname): with cache_file.open(mode="w", encoding="utf-8") as jfile: json.dump(data, jfile) + if not title or not doc: + self.logger.warn( + f"The Jupyter example {jpy_ex_file.name!s} doesn't have a parseable" + " title and/or summary" + ) + + if not title: + title = jpy_ex_file.name + + jupyter_headers[ex_category]["titles"][jpy_ex_file.name] = title jupyter_headers[ex_category]["summaries"][jpy_ex_file.name] = doc out_name = kw["output_folder"].joinpath( diff --git a/themes/cantera/templates/jupyter-example-index.tmpl b/themes/cantera/templates/jupyter-example-index.tmpl index 3664e7612..8df3f847e 100644 --- a/themes/cantera/templates/jupyter-example-index.tmpl +++ b/themes/cantera/templates/jupyter-example-index.tmpl @@ -31,7 +31,7 @@ installation required, but you cannot save and resume your work.

{% set fname = file.name %}
-
{{ fname }}
 +
{{ file_dict['titles'][fname] }}

{{ file_dict['summaries'][fname] }}

From 9c4b381e86e16c348b05738c68372538216ff92c Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Mon, 17 Jan 2022 10:32:38 -0500 Subject: [PATCH 2/7] Fix Binder link to open correct branch after master->main transition --- themes/cantera/templates/jupyter-example-index.tmpl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/themes/cantera/templates/jupyter-example-index.tmpl b/themes/cantera/templates/jupyter-example-index.tmpl index 8df3f847e..913688b9b 100644 --- a/themes/cantera/templates/jupyter-example-index.tmpl +++ b/themes/cantera/templates/jupyter-example-index.tmpl @@ -15,7 +15,7 @@ just want to experiment, you can give Cantera a test drive in the cloud. Click o below to launch an interactive environment where you can run these examples. For this, there is no installation required, but you cannot save and resume your work.

- + Binder From 07f149738d34937a53c7cd3bdf2be883484510bc Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Mon, 17 Jan 2022 16:59:17 -0500 Subject: [PATCH 3/7] Link to data files used in Jupyter examples Fixes #148 --- plugins/render_jupyter_examples.py | 9 +++++++++ themes/cantera/templates/examples.tmpl | 9 +++++++++ 2 files changed, 18 insertions(+) diff --git a/plugins/render_jupyter_examples.py b/plugins/render_jupyter_examples.py index fe517aea4..6b9467395 100644 --- a/plugins/render_jupyter_examples.py +++ b/plugins/render_jupyter_examples.py @@ -82,6 +82,14 @@ def render_example(site, kw, in_name, out_name): ipynb_html = lxml.html.fromstring(ipynb_raw) code = lxml.html.tostring(ipynb_html, encoding="unicode") + data_files = set() + pattern = re.compile(r"data/(\w*?\.\w*)") + for cell in nb_json["cells"]: + if cell["cell_type"] != "code": + continue + for match in pattern.findall(cell["source"]): + data_files.add(match) + title = in_name.name permalink = out_name.relative_to(kw["output_folder"]) @@ -89,6 +97,7 @@ def render_example(site, kw, in_name, out_name): context = { "code": code, "title": title, + "data_files": data_files, "permalink": str(permalink), "lang": kw["default_lang"], "description": title, diff --git a/themes/cantera/templates/examples.tmpl b/themes/cantera/templates/examples.tmpl index 7ebcdfa70..4a2f9e176 100644 --- a/themes/cantera/templates/examples.tmpl +++ b/themes/cantera/templates/examples.tmpl @@ -13,6 +13,15 @@ ({{ messages("Source") }}) {% endif %} + {% if data_files %} + Data files used in this example: + {% for i, file in enumerate(data_files) -%} + {{ file }} + {%- if i + 1 != data_files | length -%} + , + {% endif %} + {% endfor %} + {% endif %} {{ code }} {% endif %} {% if title.endswith('.ipynb') %} From b4269f30743d245a42793af264d6689de21daec2 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Sat, 19 Mar 2022 11:38:51 -0400 Subject: [PATCH 4/7] Use better regex for finding data files --- plugins/render_jupyter_examples.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/render_jupyter_examples.py b/plugins/render_jupyter_examples.py index 6b9467395..c6a3234ef 100644 --- a/plugins/render_jupyter_examples.py +++ b/plugins/render_jupyter_examples.py @@ -83,7 +83,7 @@ def render_example(site, kw, in_name, out_name): code = lxml.html.tostring(ipynb_html, encoding="unicode") data_files = set() - pattern = re.compile(r"data/(\w*?\.\w*)") + pattern = re.compile(r"data/([\w-]+?\.\w*)") for cell in nb_json["cells"]: if cell["cell_type"] != "code": continue From f6df7d2ffbfeaac0e8399370b08c7e43996435b1 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Sat, 19 Mar 2022 13:54:58 -0400 Subject: [PATCH 5/7] Add category for input-related Jupyter examples --- plugins/render_jupyter_examples.py | 1 + 1 file changed, 1 insertion(+) diff --git a/plugins/render_jupyter_examples.py b/plugins/render_jupyter_examples.py index c6a3234ef..b27a7d658 100644 --- a/plugins/render_jupyter_examples.py +++ b/plugins/render_jupyter_examples.py @@ -182,6 +182,7 @@ def gen_tasks(self): reactors=dict(name="Reactor Networks", files=[], summaries={}, titles={}), flames=dict(name="One-Dimensional Flames", files=[], summaries={}, titles={}), electrochemistry=dict(name="Electrochemistry", files=[], summaries={}, titles={}), + input=dict(name="Input Files", files=[], summaries={}, titles={}), ) def get_b64_str(parent, img_fname): From 1fc5e0d3a26baa52958ab1d63374dc1c1015d767 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Sat, 19 Mar 2022 14:06:12 -0400 Subject: [PATCH 6/7] Explain need to download extra data files for Jupyter examples --- themes/cantera/templates/jupyter-example-index.tmpl | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/themes/cantera/templates/jupyter-example-index.tmpl b/themes/cantera/templates/jupyter-example-index.tmpl index 913688b9b..d53e7896e 100644 --- a/themes/cantera/templates/jupyter-example-index.tmpl +++ b/themes/cantera/templates/jupyter-example-index.tmpl @@ -6,9 +6,14 @@

Cantera examples in the form of Jupyter notebooks. To see the rendered notebooks, browse the files below.

-

Existing Cantera users: If you have Cantera and the Jupyter Notebook server -installed on your local machine, simply download any Jupyter notebook by clicking the "Source" link -at the top of each example page and you should be able to run it.

+

Existing Cantera users: If you have Cantera and the Jupyter Notebook +server installed on your local machine, simply download any Jupyter notebook by clicking +the "Source" link at the top of each example page and you should be able to run it. For +some examples, you will also need to download the additional data files listed below the +"Source" link. These data files should either be placed in a subdirectory named "data" +one level up from the directory containing the notebook file, or the notebook can be +modified to point to the location of these data files on your computer. +

New Cantera Users: If you don't have an existing Cantera installation and you just want to experiment, you can give Cantera a test drive in the cloud. Click on the Binder link From 70bd0142fea85cf40bbec39f95d83342afdb5405 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Sat, 19 Mar 2022 17:31:40 -0400 Subject: [PATCH 7/7] Mention git as an option for downloading Jupyter examples --- themes/cantera/templates/jupyter-example-index.tmpl | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/themes/cantera/templates/jupyter-example-index.tmpl b/themes/cantera/templates/jupyter-example-index.tmpl index d53e7896e..79eae36ed 100644 --- a/themes/cantera/templates/jupyter-example-index.tmpl +++ b/themes/cantera/templates/jupyter-example-index.tmpl @@ -12,7 +12,10 @@ the "Source" link at the top of each example page and you should be able to run some examples, you will also need to download the additional data files listed below the "Source" link. These data files should either be placed in a subdirectory named "data" one level up from the directory containing the notebook file, or the notebook can be -modified to point to the location of these data files on your computer. +modified to point to the location of these data files on your computer. Alternatively, +you can download all of these examples and their accompanying data files by cloning the +cantera-jupyter repository from +GitHub.

New Cantera Users: If you don't have an existing Cantera installation and you