new tutorials for C api

docs/src/conf.py

@@ -1,6 +1,8 @@
+import glob
 import os
 import subprocess
 import sys
+import zipfile
 from datetime import datetime
 
 from sphinx.domains.c import CObject
@@ -103,10 +105,37 @@ def generate_examples():
     os.environ["METATENSOR_IMPORT_FOR_SPHINX"] = "1"
 
 
+# Extra files (globs relative to the example directory) to add to the zip files
+# sphinx-gallery generates for the corresponding gallery.
+EXTRA_ZIP_FILES = {
+    "c": ["utils/*.h"],
+}
+
+
+def add_extra_files_to_zips(app):
+    """Add the files from ``EXTRA_ZIP_FILES`` to the corresponding gallery zip files."""
+    for example, patterns in EXTRA_ZIP_FILES.items():
+        examples_dir = os.path.join(ROOT, "examples", example)
+        gallery_dir = os.path.join(ROOT, "docs", "src", "examples", example)
+
+        files = []
+        for pattern in patterns:
+            files += glob.glob(pattern, root_dir=examples_dir, recursive=True)
+        names = sorted(file.replace(os.sep, "/") for file in files)
+
+        for zip_path in glob.glob(os.path.join(gallery_dir, "*.zip")):
+            with zipfile.ZipFile(zip_path, mode="a") as archive:
+                included = set(archive.namelist())
+                for name in names:
+                    if name not in included:
+                        archive.write(os.path.join(examples_dir, name), name)
+
+
 def setup(app):
     build_doxygen_docs()
     generate_examples()
 
+    app.connect("builder-inited", add_extra_files_to_zips, priority=600)
     app.add_css_file("css/metatomic.css")
 
 

docs/src/examples/index.rst

@@ -43,7 +43,7 @@ existing metatomic models with existing simulation engines.
 --------------------------------------------------------------------------------
 
 The second set of tutorials on this page is intended for developers who want to
-use ``metatomic`` to either create new models, or run exising models in a new
+use ``metatomic`` to either create new models, or run existing models in a new
 simulation engine. These tutorials require existing knowledge of the
 corresponding programming languages and machine learning frameworks.
 

examples/c/1-create-system.c

@@ -74,8 +74,8 @@ void dlpack_deleter(DLManagedTensorVersioned *self) {
 
 static DLManagedTensorVersioned* tensor_from_data(
     void *data,
-    int32_t ndim,
     const int64_t *shape,
+    int32_t ndim,
     DLDataType dtype
 ) {
     CustomDLPackContext* ctx = malloc(sizeof(CustomDLPackContext));
@@ -168,15 +168,15 @@ double cell_data[] = {
 
 DLManagedTensorVersioned* positions = tensor_from_data(
     /*data=*/ positions_data,
-    /*ndim=*/ 2,
     /*shape=*/(int64_t[]){n_atoms, 3},
+    /*ndim=*/ 2,
     /*dtype=*/(DLDataType){.code = kDLFloat, .bits = 64, .lanes = 1}
 );
 
 DLManagedTensorVersioned* cell = tensor_from_data(
     /*data=*/ cell_data,
-    /*ndim=*/ 2,
     /*shape=*/(int64_t[]){3, 3},
+    /*ndim=*/ 2,
     /*dtype=*/(DLDataType){.code = kDLFloat, .bits = 64, .lanes = 1}
 );
 
@@ -197,8 +197,8 @@ int32_t types_data[] = {
 
 DLManagedTensorVersioned *types = tensor_from_data(
     /*data=*/ types_data,
-    /*ndim=*/ 1,
     /*shape=*/(int64_t[]){n_atoms},
+    /*ndim=*/ 1,
     /*dtype=*/(DLDataType){.code = kDLInt, .bits = 32, .lanes = 1}
 );
 
@@ -213,8 +213,8 @@ DLManagedTensorVersioned *types = tensor_from_data(
 bool pbc_data[] = {true, true, true};
 DLManagedTensorVersioned *pbc = tensor_from_data(
     /*data=*/ pbc_data,
-    /*ndim=*/ 1,
     /*shape=*/(int64_t[]){3},
+    /*ndim=*/ 1,
     /*dtype=*/(DLDataType){.code = kDLBool, .bits = 8, .lanes = 1}
 );