improve documentation

[ianhi]

Having written the entire library I'm finding it difficult to figure out which parts need the most explanation. So the narrative documentation is a bit lacking although I think the examples are pretty good. Although even the examples do not cover every case.

[samanthahamilton]

Hi Ian,

I'd be more than happy to go through the pages and make editing suggestions for readability/narrative. I can start with the README, and if you like the changes, I can go through the other documentation.

Let me know,
Sam.

[ianhi]

Hiya,

By all means please do :)

As I said in the original post I've become a little bit out of touch with what a newcomer to this repo will find confusing. So I'm definitely curious what parts you find most confusing. Feel free to ask any clarifying questions!

For you, anyone, or even future me: If you are interested in in modifying the documentation then the steps get it to build are:

cd mpl-interactions
pip install .[docs]
cd docs
make html

which should make html files appear docs/_build so I then open the docs from the command line with firefox _build/index.html

out of curiosity how did you find this? I only recently made it a serious thing and I can't say I've really advertised it much/at all

[ianhi]

@samanthahamilton I took the (hopefully not creepy?) step of looking at your github readme and saw:

I’m looking to collaborate on: Projects that need help with editing, documentation, and communication

That's so rad! Writing good documentation is really difficult and improvements in vein will have a truly outsize impact. Given the importance of good documentation I want to note that while I'm more than happy for you to contribute to this library, I'd recommend focusing on a few other libraries in this ecosystem. There are foundational libraries that have serious holes or issues with their documentation. I think you will be able to have an even more positive impact working on documentation for some of those projects than this one. This is due to both their larger userbases, and their size/complexity. Below are some suggestions of high impact places to improve documentation. I mean to offer these as helpful suggestions for orienting yourself based on my experience of where the gaps are - you should obvs do whatever makes you happiest.

Other projects that need help with documentation:
ipympl
(matplotilb in the notebook - this project is built on that)
documentation: matplotlib/ipympl#208
my open PR adding examples: matplotlib/ipympl#244

ipywidgets (also used heavily by this project)
It's wildly useful but many things are unclear or missing from the docs

• Documentation incomplete jupyter-widgets/ipywidgets#2776
• https://github.com/jupyter-widgets/ipywidgets/issues?q=is%3Aopen+is%3Aissue+label%3Adocs

custom ipywidgets
ipywidgets also provides a framework for anyone to make custom widgets (for example ipympl is itself built on that framework as are the examples here) Unfortunately the documentation on how to do this is essentially non-existant

• Discussed somewhat here: Cookiecutter based tutorial jupyter-widgets/ipywidgets#2731
• I also started creating my own unofficial docs on how to this: https://github.com/ianhi/custom-ipywidget-howto
  • Unfortunately they're a bit of a mess as I kept a strict rule of "quality is not key" in order to encourage writing down things as I learned them so the task wasn't overwhelming.

ipycytoscape
Interactive graphs in the notebook used by many people. This is less foundational but also somewhere where docs would be great. Unfortunately neither mariana (the creator), nor I have had time to create docs (though there are good examples):

• Create docs cytoscape/ipycytoscape#101

In all the above I've wavered in the level of knowledge you have of this ecosystem, sorry if I got it wrong at some points but I just wasn't sure. As part of that wavering I never defined widgets in the above. So just in case: widgets are basically javascript based UIs that are easily connected to python - explained in more detail here with great examples here or https://jupyter.org/widgets

Also, as a counterpoint to the above suggestions, mpl_interactions may actually be a good starting point for documentation in this ecosystem on account of it being simpler than the others. But anyway...

[samanthahamilton]

Hey Ian,

Thanks for the warm welcome. And thanks for all the info! To answer your question, I found this repository because of the labels you included. I Googled, "documentation help wanted github" and it took me here, where I can screen for projects where I think I might be helpful. And I agree, I will start with mpl_interactions and then I'll be sure to check out those other projects.

Sam.

[ianhi]

woops I didn't intend to close this after fixing up the readme

[samanthahamilton]

Hey @ianhi,

First, the documentation build steps above worked perfectly (well, once pip was installed, etc).

which should make html files appear docs/_build

This is true, however, I've run into 2 problems I could use your help with:

1. Entering firefox _build/index.html gives me a message saying, "firefox is not recognized as an internal or external command, operable program or batch file." That said, I can double click a changed file and have it open in Firefox to display those changes. Do you have any suggestions for this error message? Have you encountered it before?

2. I think there might be a .gitignore on your _build file??? I've made some local changes in a new branch on index.html but the changes don't "register" or appear in GitHub Desktop. Gitignore is the only "answer" I could find when trying to troubleshoot. Do you have any ideas?

Thanks!

[ianhi]

Hiya

above worked perfectly (well, once pip was installed, etc).

🎉

1. That makes sense, I think it comes down to how firefox is installed. I'm on linux so it's easy to run firefox from the command line, I would not expect that be easy from windows though. I just suggested that as a convenient way to open the file, but you can open it by double clicking and that shouldn't be an issue. Also firefox is just the browser I use, but I shouldn't matter what browser you use.

2. Indeed I have excluded the _build directory: 9697a1d. I should have explained that better sorry. _build is a directory where you will be able to see the changes but I've stopped storing the generated HTML in the git repository. The HTML files on the web are not actually stored on the github page.

Instead the intended workflow is:

1. You make changes to the source files
2. make the html files and view the changes locally
3. push the changes to the source files
4. I merge them into the master branch
5. readthedocs detects the push to the master branch and builds the documentation on their servers and then the rendered docs become available here: https://mpl-interactions.readthedocs.io/en/latest/

[ianhi]

Also, I should mention. If you want to mess around with the structure of files in the docs or play with the config files you should totally just go for it. I.e. feel free to use as a playground to explore your preferences with sphinx documentation. The docs aren't very good now so it will probably only make it better ultimately. In end so long as the result builds on readthedocs and has a reasonable structure I'm happy.

[ianhi]

Closing this now due to the heroics of @samanthahamilton