From c773341764d3bc2b277b6befccfa6169bbb1e790 Mon Sep 17 00:00:00 2001 From: Michele Ceriotti Date: Wed, 14 Aug 2024 16:17:19 +0200 Subject: [PATCH 1/3] Provide a mechanism to download data for the example This is for small data files that are not worth making a zotero link --- CONTRIBUTING.rst | 13 ++++++++++--- docs/src/conf.py | 9 ++++----- examples/path-integrals/{ => data}/in.lmp | 2 +- .../path-integrals/{ => data}/input_piglet.xml | 2 +- .../path-integrals/{ => data}/input_pimd.xml | 2 +- .../path-integrals/{ => data}/water_32.pdb | 0 .../{ => data}/water_32_data.lmp | 0 examples/path-integrals/path-integrals.py | 16 ++++++++-------- generate-gallery.py | 2 +- noxfile.py | 18 ++++++++++++++++++ 10 files changed, 44 insertions(+), 20 deletions(-) rename examples/path-integrals/{ => data}/in.lmp (93%) rename examples/path-integrals/{ => data}/input_piglet.xml (99%) rename examples/path-integrals/{ => data}/input_pimd.xml (95%) rename examples/path-integrals/{ => data}/water_32.pdb (100%) rename examples/path-integrals/{ => data}/water_32_data.lmp (100%) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 18f0dc37..b4ad27e9 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -34,13 +34,20 @@ following files inside: - as many Python files as you want, each one will be converted to a separate HTML page. +Keep in mind that sphinx-gallery will make it easy to download a Python file and +the notebook generated from it, but it won't give direct access to additional +files. If your example needs such data files, there are a few options available: + +- (preferred) have the data file stored in a publicly accessible location, e.g. + a Zotero record, and download the data file from the script +- if the data files are small (few 10s of Kb) you may also include them in a + ``data/`` folder within the example folder. A zip file will be generated that + can be downloaded from the example page. + .. _sphinx-gallery: https://sphinx-gallery.github.io/ .. _RestructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html .. _conda: https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#create-env-file-manually -Finally, you'll need to add your example to the list so it is automatically -build on CI. The list is in the ``.github/workflows/docs.yml`` file, near the -``example-name:`` section. Converting a Jupyter notebook to a sphinx-gallery compatible Python script -------------------------------------------------------------------------- diff --git a/docs/src/conf.py b/docs/src/conf.py index 6d111044..1ae9d203 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -20,10 +20,6 @@ "Atomistic cookbook team" ) -htmlhelp_basename = "Atomistic cookbook" -html_theme = "furo" - - intersphinx_mapping = { "ase": ("https://wiki.fysik.dtu.dk/ase/", None), "metatensor": ("https://lab-cosmo.github.io/metatensor/latest/", None), @@ -35,11 +31,14 @@ } html_js_files = [ - ( + ( # plausible.io tracking "https://plausible.io/js/script.js", {"data-domain": "lab-cosmo.github.io/atomistic-cookbook", "defer": "defer"}, ), ] +htmlhelp_basename = "Atomistic cookbook" +html_theme = "furo" html_static_path = [os.path.join("..", "_static")] html_favicon = "../_static/cookbook-icon.png" +html_logo = "../_static/cookbook-icon.svg" diff --git a/examples/path-integrals/in.lmp b/examples/path-integrals/data/in.lmp similarity index 93% rename from examples/path-integrals/in.lmp rename to examples/path-integrals/data/in.lmp index eaeec361..2b49b207 100644 --- a/examples/path-integrals/in.lmp +++ b/examples/path-integrals/data/in.lmp @@ -6,7 +6,7 @@ bond_style class2 angle_style harmonic kspace_style pppm/tip4p 0.0001 -read_data water_32_data.lmp +read_data data/water_32_data.lmp pair_coeff * * 0 0 pair_coeff 1 1 0.000295147 5.96946 diff --git a/examples/path-integrals/input_piglet.xml b/examples/path-integrals/data/input_piglet.xml similarity index 99% rename from examples/path-integrals/input_piglet.xml rename to examples/path-integrals/data/input_piglet.xml index 89866cb7..4dfac543 100644 --- a/examples/path-integrals/input_piglet.xml +++ b/examples/path-integrals/data/input_piglet.xml @@ -14,7 +14,7 @@ - water_32.pdb + data/water_32.pdb 298 diff --git a/examples/path-integrals/input_pimd.xml b/examples/path-integrals/data/input_pimd.xml similarity index 95% rename from examples/path-integrals/input_pimd.xml rename to examples/path-integrals/data/input_pimd.xml index 9d81b968..92f8626c 100644 --- a/examples/path-integrals/input_pimd.xml +++ b/examples/path-integrals/data/input_pimd.xml @@ -14,7 +14,7 @@ - water_32.pdb + data/water_32.pdb 298 diff --git a/examples/path-integrals/water_32.pdb b/examples/path-integrals/data/water_32.pdb similarity index 100% rename from examples/path-integrals/water_32.pdb rename to examples/path-integrals/data/water_32.pdb diff --git a/examples/path-integrals/water_32_data.lmp b/examples/path-integrals/data/water_32_data.lmp similarity index 100% rename from examples/path-integrals/water_32_data.lmp rename to examples/path-integrals/data/water_32_data.lmp diff --git a/examples/path-integrals/path-integrals.py b/examples/path-integrals/path-integrals.py index 251196ea..73b24c53 100644 --- a/examples/path-integrals/path-integrals.py +++ b/examples/path-integrals/path-integrals.py @@ -68,7 +68,7 @@ # An i-PI calculation is specified by an XML file. # Open and read the XML file -with open("input_pimd.xml", "r") as file: +with open("data/input_pimd.xml", "r") as file: xml_content = file.read() print(xml_content) @@ -88,10 +88,10 @@ # # .. code-block:: bash # -# i-pi input_pimd.xml > log & +# i-pi data/input_pimd.xml > log & # sleep 2 -# lmp -in in.lmp & -# lmp -in in.lmp & +# lmp -in data/in.lmp & +# lmp -in data/in.lmp & # # Note how ``i-PI`` and ``LAMMPS`` are completely independent, and # therefore need a separate set of input files. The client-side communication @@ -100,9 +100,9 @@ # # We can launch the external processes from a Python script as follows -ipi_process = subprocess.Popen(["i-pi", "input_pimd.xml"]) +ipi_process = subprocess.Popen(["i-pi", "data/input_pimd.xml"]) time.sleep(2) # wait for i-PI to start -lmp_process = [subprocess.Popen(["lmp", "-in", "in.lmp"]) for i in range(2)] +lmp_process = [subprocess.Popen(["lmp", "-in", "data/in.lmp"]) for i in range(2)] # %% # If you run this in a notebook, you can go ahead and start loading @@ -216,9 +216,9 @@ # `the GLE4MD website `_ # -ipi_process = subprocess.Popen(["i-pi", "input_piglet.xml"]) +ipi_process = subprocess.Popen(["i-pi", "data/input_piglet.xml"]) time.sleep(2) # wait for i-PI to start -lmp_process = [subprocess.Popen(["lmp", "-in", "in.lmp"]) for i in range(2)] +lmp_process = [subprocess.Popen(["lmp", "-in", "data/in.lmp"]) for i in range(2)] ipi_process.wait() lmp_process[0].wait() diff --git a/generate-gallery.py b/generate-gallery.py index 221a533a..850c8e4c 100644 --- a/generate-gallery.py +++ b/generate-gallery.py @@ -41,7 +41,7 @@ def __init__(self, example): "examples_dirs": os.path.join(HERE, example), "gallery_dirs": gallery_dir, "min_reported_time": 60, - "copyfile_regex": r".*\.(sh|xyz|cp2k|yml|png)", + "copyfile_regex": r".*\.(sh|xyz|cp2k|yml|png|zip)", "matplotlib_animations": True, "within_subsection_order": "FileNameSortKey", "image_scrapers": ("matplotlib", ChemiscopeScraper()), diff --git a/noxfile.py b/noxfile.py index 04866437..ed586a1e 100644 --- a/noxfile.py +++ b/noxfile.py @@ -2,6 +2,7 @@ import hashlib import json import os +import shutil import subprocess import sys @@ -141,7 +142,14 @@ def example(session, name=name): "chemiscope", ) + # Creates data.zip if there's a data folder + if os.path.exists(f"examples/{name}/data"): + shutil.make_archive( + f"examples/{name}/data", "zip", f"examples/{name}/", "data/" + ) + session.run("python", "generate-gallery.py", f"examples/{name}") + os.unlink(f"docs/src/examples/{name}/index.rst") if "--no-build-docs" not in session.posargs: @@ -183,6 +191,7 @@ def build_docs(session): ) for file in glob.glob("docs/src/examples/*/*.rst"): if os.path.basename(file) != "sg_execution_times.rst": + root = os.path.dirname(file) path = file[9:-4] output.write(f" {path}\n") @@ -208,6 +217,15 @@ def build_docs(session): """ ) + if os.path.join(root, "data.zip"): + fd.write( + """ + .. container:: sphx-glr-download + + :download:`Download data file: data.zip ` +""" + ) + fd.write(line) fd.write("\n") From 7cece4fda4b3a2002cbfac75c08b589ed9e50c3f Mon Sep 17 00:00:00 2001 From: Michele Ceriotti Date: Wed, 14 Aug 2024 16:18:07 +0200 Subject: [PATCH 2/3] Add a logo --- docs/_static/cookbook-icon.svg | 283 +++++++++++++++++++++++++++++++++ 1 file changed, 283 insertions(+) create mode 100644 docs/_static/cookbook-icon.svg diff --git a/docs/_static/cookbook-icon.svg b/docs/_static/cookbook-icon.svg new file mode 100644 index 00000000..6852f0fe --- /dev/null +++ b/docs/_static/cookbook-icon.svg @@ -0,0 +1,283 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From 7df30b98e6aa54e4c9d81cd5eb1619ce4d3dbd45 Mon Sep 17 00:00:00 2001 From: Michele Ceriotti Date: Wed, 14 Aug 2024 16:24:24 +0200 Subject: [PATCH 3/3] Lint --- CONTRIBUTING.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index b4ad27e9..ac17dbf0 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -35,14 +35,14 @@ following files inside: HTML page. Keep in mind that sphinx-gallery will make it easy to download a Python file and -the notebook generated from it, but it won't give direct access to additional +the notebook generated from it, but it won't give direct access to additional files. If your example needs such data files, there are a few options available: - (preferred) have the data file stored in a publicly accessible location, e.g. a Zotero record, and download the data file from the script -- if the data files are small (few 10s of Kb) you may also include them in a +- if the data files are small (few 10s of Kb) you may also include them in a ``data/`` folder within the example folder. A zip file will be generated that - can be downloaded from the example page. + can be downloaded from the example page. .. _sphinx-gallery: https://sphinx-gallery.github.io/ .. _RestructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html