Organize Locations of Examples in Repo

[kkappler]

We currently have examples in three places. These examples are likely to grow as we develop notebooks for training.

We should:

• [x] Decide on the overall structure of the notebook archive aurora/tutorials will have detailed examples suitable for sharing to a wide audience aurora/examples\notebooks will have shorter examples that more advanced users can access. Another repository, mt_examples will be developed for workshops.
• [x] Move the files to their proper locations based on the above
• [x] Address the issue that completed ipynb do not run in continuous integration tests, so we are curating stale examples This could be addressed by
  1. keeping two versions of the ipynb, one blank and one completed, so the blank runs on commit
  2. Making a test.py file that mirrors the ipynb (seems like more work)
  3. better solutions are discussed here
• [x] PR & Merge

[kkappler]

@kujaku11 PTAL the above and LMK if we should @others (Lindsey, Tim, Joe) for advice on this.

Specifically, should all examples live in one folder? Or some under aurora/docs/examples /aurora/docs/notebooks and some under aurora/examples?

My first thought is that they should all be kept together, but I do not know what the pros and cons are of placing things under doc/.

This article seems relevant: https://mg.readthedocs.io/git-jupyter.html

[kkappler]

We will consolidate the ipython notebooks into aurora/docs/examples

[kkappler]

When I consolidate to docs/examples I get a failure on test_doc_build.py.

Extension error: Example directory /home/kkappler/software/irismt/aurora/docs/../examples does not have a README file with one of the expected file extensions ['.txt', '.ipynb', '.rst']. Please write one to introduce your gallery. Makefile:20: recipe for target 'html' failed make: *** [html] Error 2 F

FAIL: test_html (main.Doc_Test)

Traceback (most recent call last): File "test_doc_build.py", line 19, in test_html self.assertTrue(response.returncode == 0) AssertionError: False is not true

---

Ran 1 test in 3.907s

This is because docs/conf.py expects the examples folder

Sphinx Gallery

sphinx_gallery_conf = {

path to your examples scripts

"examples_dirs": [ "../examples", ], "gallery_dirs": [ "examples", ], "within_subsection_order": FileNameSortKey, "filename_pattern": ".py", "backreferences_dir": "api/generated/backreferences", "doc_module": "aurora",

'reference_url': {'discretize': None},

Reading the sphinx docs:https://sphinx-gallery.github.io/stable/configuration.html#multiple-galleries-config

Sphinx-Gallery only supports up to sub-folder level in its gallery directories. This might be a limitation for you. Or you might want to have separate galleries for different purposes, an examples gallery and a tutorials gallery.

Leaves me uncertain about the recommended structure.

At least there are only two and not three places with .ipynb now.

[kkappler]

The next step is to figure out the intended difference between aurora/docs/examples and aurora/examples, and best practices.

Maybe, should I be moving tests/cas04/ to examples/cas04?

[kkappler]

Rename high level examples folder as tutorials

[kkappler]

This issue went stale but is being handled as part of the joss manuscript and issue #337.

Currently this PR , once merged should resolve issue 194.

[kkappler]

At long last we have arrived at a system of docs/tutorials and docs/examples as of release 0.4.1.