Skip to content

[Docs] Executable notebook tutorial#22030

Merged
krfricke merged 9 commits intomasterfrom
mp_executable_notebooks
Feb 3, 2022
Merged

[Docs] Executable notebook tutorial#22030
krfricke merged 9 commits intomasterfrom
mp_executable_notebooks

Conversation

@maxpumperla
Copy link
Copy Markdown
Contributor

@maxpumperla maxpumperla commented Feb 1, 2022

We're introducing the usage of MyST Notebooks here and demonstrate how it works by rewriting (and extending) the RLLib Serve tutorial. Benefits:

  • Write notebooks in markdown. Can be converted into other formats e.g. with jupytext
  • Tutorials like this have a binderhub link added to the top nav (launch button).
  • Notebooks get executed when docs are built, so it's impossible to have stale docs.
  • But locally those builds are cached so that you don't have to wait too long.
  • The notebook cell outputs can be shown, hidden or removed. In particular, we can now avoid adding expected code output as comments in our scripts (which might get outdated).

We're also clarifying #22022.

@simon-mo let me know what you think about this. A "drawback" of this approach is that we're not using literalinclude anymore. The jupyter philosophy is to keep text and code in a common source. But then again, I'm not sure these snippets here are actually tested anyway.

Old tutorial: here
New tutorial (preview): here

@maxpumperla maxpumperla self-assigned this Feb 1, 2022
@maxpumperla maxpumperla added the docs An issue or change related to documentation label Feb 1, 2022
@maxpumperla
Copy link
Copy Markdown
Contributor Author

maxpumperla commented Feb 1, 2022

@richardliaw do you know how to access readthedocs.org log files? Specifically the one mentioned here:

WARNING: Execution Failed: /home/docs/checkouts/readthedocs.org/user_builds/ray/checkouts/22030/doc/source/serve/tutorials/rllib.md
WARNING: Couldn't find cache key for notebook file serve/tutorials/rllib.md. Outputs will not be inserted.
  Last execution failed with traceback saved in /home/docs/checkouts/readthedocs.org/user_builds/ray/checkouts/22030/doc/source/_build/html/reports/rllib.log
looking for now-outdated files... none found
pickling environment... done

it seems like the build can't find rllib (at least that's my guess). In commit b5abcd9 i've installed ray[tune, rllib, serve] which made readthedocs happy. In docs code we have the following passage in conf.py:

sys.path.insert(0, os.path.abspath("../../python/"))

this should take care of having access to all Ray libs, but doesn't. The problem is, I can't reproduce this issue locally. Starting from a fresh venv, everything is fine for me.

@simon-mo
Copy link
Copy Markdown
Contributor

simon-mo commented Feb 1, 2022

One issue I foresee is that when building the doc in readthedocs, their server doesn't have enough resource to let us execute end to end.

@maxpumperla
Copy link
Copy Markdown
Contributor Author

@simon-mo I've made notebook execution configurable. By default, readthedocs will not have to run them, but we can force that behaviour on CI like this:

RUN_NOTEBOOKS="force" sphinx-build -b html -d _build/doctrees  source _build/html

Not necessary right now, can be added later.

@simon-mo simon-mo self-assigned this Feb 2, 2022
@simon-mo
Copy link
Copy Markdown
Contributor

simon-mo commented Feb 2, 2022

@maxpumperla this is great! I think this will definitely work in readthedocs environment now. However, how can we execute as a test case in CI now we don't have the python script anymore? It would be great if we can change the bazel rule in python/ray/serve/BUILD's test_rllib_tutorial to executing this. Thanks!

@krfricke krfricke merged commit 0925987 into master Feb 3, 2022
@krfricke krfricke deleted the mp_executable_notebooks branch February 3, 2022 08:13
krfricke added a commit that referenced this pull request Feb 7, 2022
Continuing docs overhaul, tune now has:

- [x] better landing page
- [x] a getting started guide
- [x] user guide was cut down, partially merged with FAQ, and partially integrated with tutorials
- [x] the new user guide contains guides to tune features and practical integrations
- [x] we rewrote some of the feature guides for clarity 
- [x] we got rid of sphinx-gallery for this sub-project (only data and core left), as it looks bad and is unnecessarily complicated anyway (plus, makes the build slower)
- [x] sphinx-gallery examples are now moved to markdown notebook, as started in #22030.
- [x] Examples are tested in the new framework, of course.

There's still a lot one can do, but this is already getting too large. Will follow up with more fine-tuning next week.

Co-authored-by: Antoni Baum <antoni.baum@protonmail.com>
Co-authored-by: Kai Fricke <krfricke@users.noreply.github.com>
maxpumperla added a commit that referenced this pull request Feb 18, 2022
We're introducing the usage of [MyST Notebooks](https://myst-nb.readthedocs.io/en/latest/index.html) here and demonstrate how it works by rewriting (and extending) the RLLib Serve tutorial. Benefits:

- [x] Write notebooks in markdown. Can be converted into other formats e.g. with `jupytext`
- [x] Tutorials like this have a binderhub link added to the top nav (launch button).
- [x] Notebooks get executed when docs are built, so it's impossible to have stale docs.
- [x] But locally those builds are cached so that you don't have to wait too long.
- [x] The notebook cell outputs can be shown, hidden or removed.  In particular, we can now avoid adding expected code output as comments in our scripts (which might get outdated).

We're also clarifying  #22022.

Old tutorial: [here](https://docs.ray.io/en/latest/serve/tutorials/rllib.html)
New tutorial (preview): [here](https://ray--22030.org.readthedocs.build/en/22030/serve/tutorials/rllib.html)

Co-authored-by: simon-mo <simon.mo@hey.com>
mwtian pushed a commit that referenced this pull request Feb 19, 2022
* merge

Signed-off-by: Max Pumperla <max.pumperla@googlemail.com>

* [Docs] Executable notebook tutorial (#22030)

We're introducing the usage of [MyST Notebooks](https://myst-nb.readthedocs.io/en/latest/index.html) here and demonstrate how it works by rewriting (and extending) the RLLib Serve tutorial. Benefits:

- [x] Write notebooks in markdown. Can be converted into other formats e.g. with `jupytext`
- [x] Tutorials like this have a binderhub link added to the top nav (launch button).
- [x] Notebooks get executed when docs are built, so it's impossible to have stale docs.
- [x] But locally those builds are cached so that you don't have to wait too long.
- [x] The notebook cell outputs can be shown, hidden or removed.  In particular, we can now avoid adding expected code output as comments in our scripts (which might get outdated).

We're also clarifying  #22022.

Old tutorial: [here](https://docs.ray.io/en/latest/serve/tutorials/rllib.html)
New tutorial (preview): [here](https://ray--22030.org.readthedocs.build/en/22030/serve/tutorials/rllib.html)

Co-authored-by: simon-mo <simon.mo@hey.com>

* lint

Signed-off-by: Max Pumperla <max.pumperla@googlemail.com>

Co-authored-by: simon-mo <simon.mo@hey.com>
simonsays1980 pushed a commit to simonsays1980/ray that referenced this pull request Feb 27, 2022
Continuing docs overhaul, tune now has:

- [x] better landing page
- [x] a getting started guide
- [x] user guide was cut down, partially merged with FAQ, and partially integrated with tutorials
- [x] the new user guide contains guides to tune features and practical integrations
- [x] we rewrote some of the feature guides for clarity 
- [x] we got rid of sphinx-gallery for this sub-project (only data and core left), as it looks bad and is unnecessarily complicated anyway (plus, makes the build slower)
- [x] sphinx-gallery examples are now moved to markdown notebook, as started in ray-project#22030.
- [x] Examples are tested in the new framework, of course.

There's still a lot one can do, but this is already getting too large. Will follow up with more fine-tuning next week.

Co-authored-by: Antoni Baum <antoni.baum@protonmail.com>
Co-authored-by: Kai Fricke <krfricke@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs An issue or change related to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants