Conversation
autogenerate literal include docs for all examples. The code is self maintaining: if examples are removed or added the docs are also updated.
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
EwoutH
left a comment
EwoutH
left a comment
There was a problem hiding this comment.
Sorry for the late review, missed the notification.
One minor comment: Can we split the .py files from the Jupyter Notebooks on the Examples page? It would be nice if the notebooks were listed under their own heading, since they also offer more explanation and such.
| @@ -0,0 +1,110 @@ | |||
| # Changelog | |||
There was a problem hiding this comment.
Is adding this changelog.md an intended change?
There was a problem hiding this comment.
Happens as part of the built process of the docs. While working on it, I tested it locally, hence the updated file. In principle, it can be removed.
|
I use the glob directive to create the index on examples.rst. Glob is quite restrictive. The only way to do something like you suggest is to separate the examples into a notebooks folder and .py folder. |
| fn = os.path.join(HERE, "examples", entry) | ||
| os.remove(fn) | ||
|
|
||
| notebooks = glob.glob(examples_folder + "/*.ipynb") |
There was a problem hiding this comment.
You're already collecting notebooks here separately. Isn't it possible to put them under an separate header?
There was a problem hiding this comment.
It is always possible of course. It requires, however, using yet another string template just as I do for generating all .rst files for the examples. I'll take a look today.
by the way, I was referring to the sphinx glob directive as used here: https://github.com/quaquel/EMAworkbench/blob/examples_docs/docs/source/examples.rst
|
Thanks, while I think having them listed a under separate headers would be nicer, it's a good first iteration for now and way better then not having them listed at all. If you can figure out how to put them in separate lists that would be awesome, if not feel free to merge (I recommend squashing) as it is. |
|
Turned out to be relatively straightforward in the end: https://emaworkbench--244.org.readthedocs.build/en/244/examples.html. And I agree: this looks much cleaner. |
|
Awesome work, this indeed looks great! |
3 participants
This pull request adds the examples from the examples folder to the documentation. See https://emaworkbench.readthedocs.io/en/examples_docs/examples.html for an overview.
As part of this, I have also renamed all examples to follow a consistent pattern making it easier to find specific examples.