Comments (9)
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.
from mpl-interactions.
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
from mpl-interactions.
@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
- 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: 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):
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...
from mpl-interactions.
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.
from mpl-interactions.
woops I didn't intend to close this after fixing up the readme
from mpl-interactions.
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:
-
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? -
I think there might be a
.gitignore
on your_build
file??? I've made some local changes in a new branch onindex.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!
from mpl-interactions.
Hiya
above worked perfectly (well, once pip was installed, etc).
š
-
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.
-
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:
- You make changes to the source files
- make the html files and view the changes locally
- push the changes to the source files
- I merge them into the master branch
- 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/
from mpl-interactions.
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.
from mpl-interactions.
Closing this now due to the heroics of @samanthahamilton
from mpl-interactions.
Related Issues (20)
- panhandler doesn't work when you call from another function HOT 4
- Add example of using mpl-interactions as an engine for updating without sliders HOT 2
- Better testing
- Add conda forge install instructions
- Syntax Error in controller.py HOT 7
- add `eventplot` function
- Dynamically update `fontdict` for `iplt.text`
- Didn't find the package using Mamba HOT 2
- sliders not showing with ipywidgets 8.0.1 HOT 2
- NameError: name 'display' is not defined HOT 2
- image_segmenter: Enable saving of verts or path coordinates for a image_segmenter object HOT 11
- Git-Issue: Can't commit to my fork of mpl-interactions HOT 5
- Hyperslicer not producing same image as imshow for xarray HOT 3
- Check behavior of hyperslicer `names` and `axes` arguments.
- Set initial slider position in Hyperslicer HOT 3
- panhandler not working when plot embedded in pyqt5 HOT 2
- joss review: installation issues HOT 3
- joss review: writing comments HOT 2
- Joss review: authorship HOT 7
- [JOSS review]: state of the field HOT 5
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
š Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. ššš
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ā¤ļø Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from mpl-interactions.