Create docs

[ianhi]

Scattered over a few issues there has been mention of the need for a documentation page. This is a first pass at creating one. I think there are lots of great things we can add (e.g. css tricks #411 (comment)) but getting something out there is more important than getting everything in there. I think it's important for users to be able to go to a website to get install instructions rather than a github repo as I suspect that this is lends a sense of stability and officiallness to the project. It also makes it easier to have much more robust sections on installing and contributing.

I think the big question I have is probably primarily for @tacaswell (and also @martinRenou ) which is where should this be hosted? I know how to set things up on readthedocs and so can can easily do that. But this is also a matplotlib subproject (unclear how official that makes things) and does that mean that this shoudl be hosted on matplotlib.org/ipympl? I think that would be my preferred URL if possible.

Other thoughts:

1. One day my dream is to have the docs be immediately enabled as interactive via pyodide @martinRenou do you know how far we are from being able to do something like that?
2. We should have a more comprehensive section on using ipympl with ipywidgets
   • Thoughts on including mpl-interactions there? I'm biased but I find it to be the best way to pair ipywidgets with matplotlib.

[github-actions]

👈 Launch a binder notebook on branch ianhi/ipympl/docs

[ianhi]

Anyone have an idea if/how to get ipympl working in sagemath/cocalc?

[ianhi]

Now that there's less noise here: @williamstein I couldn't find an obvious way to do this after some brief searching and the one attempt I had didn't work. Would love to include instructions though

[martinRenou]

One day my dream is to have the docs be immediately enabled as interactive via pyodide @martinRenou do you know how far we are from being able to do something like that?

We're pretty close actually :)

I'd really like to have a simple replite console at the beginning of the docs. But this requires widgets to work in JupyterLab console jupyter-widgets/ipywidgets#3004

[martinRenou]

I'm making some experiments on jupyterlite-sphinx:

https://github.com/martinRenou/jupyterlite-sphinx
https://jupyterlite-sphinx.readthedocs.io/en/latest

[ianhi]

bump @tacaswell

[tacaswell]

I'm sorry, I wrote message here (and even checked it off my to-do list) but apparently never hit "send" 🐑 🤦🏻

I think be best path to hosting is to use something like https://github.com/matplotlib/mpl-gui/blob/main/.github/workflows/docs.yml to put the built docs on github. We just this weekend moved to self-hosting the docs on digital ocean (still behind cloudflare as a CDN). We will need to add a web-hook to notify that system when new docs are pushed.

attn @QuLogic

[martinRenou]

It would be great to add a section on how to make it work on colab:

from google.colab import output
output.enable_custom_widget_manager()

[ianhi]

I think be best path to hosting is to use something like https://github.com/matplotlib/mpl-gui/blob/main/.github/workflows/docs.yml to put the built docs on github.

I've added this. I don't suppose there's an easy way to see them rendered on a PR?

We will need to add a web-hook to notify that system when new docs are pushed.

@QuLogic any chance of this (if not already done?) I don't think there's much left to do here

[ianhi]

Ok. I think I'm happy with this now. Can someone give a read over to review?

[QuLogic]

We will need to add a web-hook to notify that system when new docs are pushed.

@QuLogic any chance of this (if not already done?) I don't think there's much left to do here

It will only make sense to do this after you have a branch with built docs in it.

[ianhi]

Ok. I think I'm happy with this now. Can someone give a read over to review?

Absent any objections I'm going to merge this. we can always iterate more later

[ianhi]

@QuLogic we now have a gh-pages branch that contains built docs

[ianhi]

@QuLogic bump - this will eventually end up at https://matplotlib.org/ipympl correct?

[tacaswell]

matplotlib/matplotlib.org#15 is step 1

[tacaswell]

I have the power to add the webhook, but I am unsure what the secret should be.

[QuLogic]

The secret is just a random set of characters.