rheiland / xml2jupyter Goto Github PK

From looking at the README, I assume that one is meant to use this script directly, instead of installing via pip etc. It would be helpful for people if there were instructions explicitly stating this, since many people will expect there to be an ## Installation category (even if the instruction just say "run git clone XXX and then see the Usage section for information on how to run the software".

It would be helpful if there were more context about the specific scientific context in which this package is useful. Because the name "xml2jupyter" is fairly generic (XML can store all kinds of information, while this package refers to a specific kind of XML), it's important to signal quickly what kind of users it is targeted toward.

The demo for this project is really cool - though it is a bit complex. I stepped through the GUI, but was still a bit unclear how I could integrate the script into my own workflow. For example, the "usage" section says that you don't technically need Jupyter to run this package, and uses the command line in its sample code, whereas the example utilizes a pre-rendered GUI. I think there should be a minimal example showing the XML structure that this supports, the command to process it, and the kind of output it generates.

There are currently fairly minimal contributing guidelines in the README - they mention GitHub issues, but nothing really about how folks can get involved with the project and submit their own pull requests, and there aren't any guidelines helping people navigate the codebase itself (e.g. how it's structured, overview of scripts/modules/etc). For example, here's a contributing file for one of our projects. You don't necessarily need that much information, but some more than just "use github issues" would be helpful.

I noticed that Travis seems to have some test code commented out:

https://github.com/rheiland/xml2jupyter/blob/master/.travis.yml#L11

Maybe I'm mis-reading that, but it seems like the tests aren't actually being run there?