Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make documentation runnable on binder #27514

Open
TomAugspurger opened this issue Jul 22, 2019 · 2 comments
Open

Make documentation runnable on binder #27514

TomAugspurger opened this issue Jul 22, 2019 · 2 comments
Labels

Comments

@TomAugspurger
Copy link
Contributor

I was playing around with a getting our docs runnable on binder today.

The tldr is that you can run them at https://mybinder.org/v2/gh/TomAugspurger/pandas-binder/master?filepath=build%2Fjupyter%2Fgetting_started%2F10min.ipynb

The source is at https://github.com/TomAugspurger/pandas-binder.


Overall, I think this is neat. It uses sphinxcontrib-jupyter to turn our (lightly modified) ReST files to Jupyter notebooks.

There are a few changes to the pandas source that I'd like to propose

  1. Adding a little boilerplate to the user guide and getting started pages to link to the runnable version (see https://github.com/dask/dask-examples/blob/d7a69122d9c1c24f6583e7d46cd089cf1eb70ae8/conf.py#L49)
  2. Maybe restructuring our jinja {{ header }} to be an explicit code block in each page (it doesn't seem to play well with sphinxcontrib-jupyter). I can probably make a workaround though.

Lots of things are probably broken (e.g. refs like :ref:DataFrame) don't resolve correctly. But I'm happy with this as a work in progress.

@ghost
Copy link

ghost commented Jul 22, 2019

I've seen other projects move towards interactive documentation. I think it's a terrific idea.

@WillAyd
Copy link
Member

WillAyd commented Jul 22, 2019

Yea I think this is cool and helpful to new users so +1 from me

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

3 participants