@@ -23,46 +23,88 @@ def copy_notebooks(notebooks, examples_dir, target_dir):
2323
2424
2525def find_notebooks (directory ):
26+ """
27+ Returns a list of notebook paths (with no file extension),
28+ relative to 'directory'. For example, if a notebook is:
29+ examples/gLV/examples-bayes-gLV.ipynb
30+ we return 'gLV/examples-bayes-gLV' (forward slashes).
31+ """
2632 notebooks = []
2733 for root , _ , files in os .walk (directory ):
2834 for file in files :
2935 if file .endswith (".ipynb" ):
3036 path = os .path .join (root , file )
3137 relative_path = os .path .relpath (path , start = directory )
32- notebooks .append (relative_path .replace (
33- os .path .sep , '/' ).replace ('.ipynb' , '' ))
38+ notebooks .append (
39+ relative_path .replace (
40+ os .path .sep , '/' ).replace ('.ipynb' , '' )
41+ )
3442 return notebooks
3543
3644
45+ def group_notebooks_by_top_dir (notebooks ):
46+ """
47+ Takes a list of relative notebook paths like ['gLV/examples-bayes-gLV', 'CRM/examples-sim-CRM']
48+ and returns a dict grouping them by the top-level folder:
49+ {
50+ 'CRM': ['CRM/examples-sim-CRM'],
51+ 'gLV': ['gLV/examples-bayes-gLV']
52+ ...
53+ }
54+ """
55+ grouped : dict [str , list [str ]] = {}
56+ for nb in notebooks :
57+ parts = nb .split ('/' )
58+ top_dir = parts [0 ] # The directory before the first slash
59+ grouped .setdefault (top_dir , []).append (nb )
60+ return grouped
61+
62+
3763def generate_rst (notebooks , target_dir , output_file ):
38- with open (output_file , 'w' ) as f :
39- f .write ("Examples\n " )
40- f .write ("========\n \n " )
41- f .write (".. toctree::\n " )
42- f .write (" :maxdepth: 2\n \n " )
43- for nb in notebooks :
44- # Notebooks are now within `docs/source/notebooks`, adjust path
45- # accordingly
46- nb_path = os .path .join ('notebooks' , nb ).replace (os .path .sep , '/' )
47- f .write (f" { nb_path } \n " )
64+ """
65+ Generates 'examples_auto.rst', grouping notebooks by their top-level folder.
66+ Each folder gets its own subheading and toctree.
67+ """
68+ grouped = group_notebooks_by_top_dir (notebooks )
69+
70+ with open (output_file , 'w' , encoding = 'utf-8' ) as f :
71+ f .write ("Jupyter Notebook Examples by Model\n " )
72+ f .write ("----------------------------------\n \n " )
73+
74+ # For each top-level folder, create a subheading and toctree
75+ # Sort the folder names so the output is consistent
76+ for folder in sorted (grouped .keys ()):
77+ f .write (folder + "\n " + "-" * len (folder ) + "\n \n " )
78+ f .write (".. toctree::\n " )
79+ f .write (" :maxdepth: 2\n \n " )
80+
81+ # Write each notebook path
82+ for nb in sorted (grouped [folder ]):
83+ # notebooks are now in docs/source/notebooks
84+ nb_path = os .path .join (
85+ 'notebooks' , nb ).replace (os .path .sep , '/' )
86+ f .write (f" { nb_path } \n " )
87+
88+ f .write ("\n " ) # blank line between sections
4889
4990
5091def main ():
92+ # Path to your top-level examples directory
5193 examples_dir = os .path .abspath ('../../examples' )
52- # Target directory within docs/source
94+
95+ # The target dir in docs/source where notebooks will be copied
5396 target_dir = os .path .join (os .path .dirname (__file__ ), 'notebooks' )
5497
55- # Clear the target directory before copying notebooks
98+ # Clear the target directory before re- copying notebooks
5699 clear_directory (target_dir )
57100
58101 notebooks = find_notebooks (examples_dir )
59102
60- # Copy notebooks to the Sphinx source directory
103+ # Copy all notebooks from examples/ to docs/ source/notebooks/
61104 copy_notebooks (notebooks , examples_dir , target_dir )
62105
63- # Now, generate examples.rst with paths relative to the new location
64- output_rst = os .path .join (os .path .dirname (__file__ ), 'examples.rst' )
65- # Ensure paths are relative to `docs/source/notebooks`
106+ # Generate 'examples_auto.rst' (instead of 'examples.rst')
107+ output_rst = os .path .join (os .path .dirname (__file__ ), 'examples_auto.rst' )
66108 generate_rst (notebooks , target_dir , output_rst )
67109 print (f"Generated { output_rst } )
68110
0 commit comments