diff --git a/.gitignore b/.gitignore index 99159a6ee..3b83c9748 100644 --- a/.gitignore +++ b/.gitignore @@ -34,3 +34,4 @@ config.log *.gcno coverage/ coverage.info +doc/sphinx/cython/examples/*.rst diff --git a/doc/SConscript b/doc/SConscript index c11344322..094fde00f 100644 --- a/doc/SConscript +++ b/doc/SConscript @@ -21,4 +21,17 @@ if localenv['sphinx_docs']: 'sphinx/conf.py', '${sphinx_cmd} -b html -d ${SPHINXBUILD}/doctrees ${SPHINXSRC} ${SPHINXBUILD}/html')) + # Python examples: Create individual documentation pages with the source + # for each example + example_root = Dir('#interfaces/cython/cantera/examples').abspath + for subdir in subdirs(example_root): + for f in mglob(env, pjoin(example_root, subdir), 'py'): + tmpenv = env.Clone() + tmpenv['script_name'] = f.name + tmpenv['script_path'] = '../../../../interfaces/cython/cantera/examples/%s/%s' % (subdir, f.name) + b = tmpenv.SubstFile('#doc/sphinx/cython/examples/%s_%s.rst' % (subdir, f.name[:-3]), + '#doc/sphinx/cython/examples/example-script.rst.in') + build(b) + localenv.Depends(sphinxdocs, b) + localenv.AlwaysBuild(sphinxdocs) diff --git a/doc/sphinx/cython/examples.rst b/doc/sphinx/cython/examples.rst new file mode 100644 index 000000000..31f6d3e8f --- /dev/null +++ b/doc/sphinx/cython/examples.rst @@ -0,0 +1,62 @@ +.. _sec-cython-examples: + +.. py:currentmodule:: cantera + +Index of Examples +================= + +This is an index of the examples included with the Cantera Python module. They +can be found in the `examples` subdirectory of the Cantera Python module's +installation directory. To determine the location of this directory, run the following in your Python interpreter:: + + import cantera.examples + print(cantera.examples.__path__) + +Thermodynamics +-------------- +.. toctree:: + :glob: + + examples/thermo* + +Kinetics +-------- +.. toctree:: + :glob: + + examples/kinetics* + +Transport +--------- +.. toctree:: + :glob: + + examples/transport* + +Reactor Networks +---------------- +.. toctree:: + :glob: + + examples/reactors* + +One-dimensional Flames +---------------------- +.. toctree:: + :glob: + + examples/onedim* + +Multiphase Mixtures +------------------- +.. toctree:: + :glob: + + examples/multiphase* + +Surface Chemistry +----------------- +.. toctree:: + :glob: + + examples/surface_chemistry* diff --git a/doc/sphinx/cython/examples/example-script.rst.in b/doc/sphinx/cython/examples/example-script.rst.in new file mode 100644 index 000000000..aa5b7f8f4 --- /dev/null +++ b/doc/sphinx/cython/examples/example-script.rst.in @@ -0,0 +1,4 @@ +@script_name@ +======================================================================= + +.. literalinclude:: @script_path@ diff --git a/doc/sphinx/cython/index.rst b/doc/sphinx/cython/index.rst index 0c81fe7f4..4cc3faa68 100644 --- a/doc/sphinx/cython/index.rst +++ b/doc/sphinx/cython/index.rst @@ -17,3 +17,4 @@ Contents: zerodim onedim constants + examples diff --git a/interfaces/cython/SConscript b/interfaces/cython/SConscript index d1416e970..4a89239cf 100644 --- a/interfaces/cython/SConscript +++ b/interfaces/cython/SConscript @@ -204,10 +204,8 @@ if localenv['python_package'] == 'new': subprocess.call(['3to2', '--no-diff', '-n', '-w','-x', 'str', '-x', 'open', target[0].abspath]) - for subdir in os.listdir('cantera/examples'): + for subdir in subdirs('cantera/examples'): dirpath = pjoin('cantera', 'examples', subdir) - if not os.path.isdir(dirpath): - continue for filename in os.listdir(dirpath): if not filename.endswith('.py'): continue diff --git a/site_scons/buildutils.py b/site_scons/buildutils.py index 918b03406..1f7d7ae16 100644 --- a/site_scons/buildutils.py +++ b/site_scons/buildutils.py @@ -12,6 +12,7 @@ import shutil import itertools import SCons.Errors +import SCons from distutils.version import LooseVersion import distutils.sysconfig @@ -405,6 +406,13 @@ def psplit(s): return path +def subdirs(path): + """ Get the subdirectories of a specified directory """ + for subdir in os.listdir(path): + dirpath = pjoin(path, subdir) + if os.path.isdir(dirpath): + yield subdir + def stripDrive(s): """ Remove a Windows drive letter specification from a path.