Closed kkappler closed 1 week ago
@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
We will consolidate the ipython notebooks into aurora/docs/examples
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.
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
?
Rename high level examples folder as tutorials
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.
At long last we have arrived at a system of docs/tutorials
and docs/examples
as of release 0.4.1
.
We currently have examples in three places. These examples are likely to grow as we develop notebooks for training.
We should:
aurora/tutorials
will have detailed examples suitable for sharing to a wide audienceaurora/examples\notebooks
will have shorter examples that more advanced users can access. Another repository,mt_examples
will be developed for workshops.