Adding a new example

There are a few "boilerplate" steps required when adding a new example.

• Set up the libmesh-specific GNU autotools by following these instructions.
• Choose a category which fits your example (adaptivity, adjoints, etc), create a new directory, and add the necessary source and header files.
• Copy a Makefile.am from one of the other examples (e.g. examples/adjoints/adjoints_ex1/Makefile.am) to your new example. Fill in the install_dir, data, and CLEANFILES variables with values relevant to your example.
• Copy over a run.sh from one of the other examples (e.g. examples/adjoints/adjoints_ex1/run.sh) and update the example_name and example_dir variables appropriately.
• Add a line to the SUBDIRS variable in examples/Makefile.am for your new example.
• Add a line to the AC_CONFIG_FILES section of top-level configure.ac for your new example.
• Run ./bootstrap at the top level.
• Check in the bootstrap changes:

  git commit -am"Ran boostrap for the new example."
  

• Add a Table of Contents entry for the new example in doc/html/src/examples.html.
• In a working libMesh build directory, generate an html-formatted landing page for the example, which will include its output. (In the steps below, replace the "category" string and example number to match your specific case.)

  cd $LIBMESH_ROOT/build/examples/category/category_ex1
  make category_ex1.html
  

• Inspect category_ex1.html and remove any performance logging or other user-specific output; these details are not necessary for documentation purposes. Also, the make run target for many examples runs the example multiple times, so it is not necessary to retain all of the example output, just enough to give a flavor of what the example does.
• Move the generated category_ex1.html file to the documentation directory and check it in:

  mv category_ex1.html $LIBMESH_ROOT/doc/html/examples
  cd $LIBMESH_ROOT
  git add doc/html/examples/category_ex1.html
  git commit -m"Add html documentation for new example."