Local load possibility and automatization of lastest remote releases added

[mondeja]

You can load local versions of the library with %%d3 local="d3.v4.min.js" (fixes #5) and the latest release stored at https://cdnjs.com/libraries/d3 is selected automatically via cdnjs API, so you don't need to hardcode them every new version. Also, I've added an argument releases that can be called as line magic (simply %d3) or cell magic (%%d3 releases) that show all available releases stored at https://cdnjs.com/libraries/d3.

[ResidentMario]

Very cool! :smile: I'll hopefully take a look at this on the weekend.

[mondeja]

• 4 fixed prohibiting users to run a second cell with another version of D3 and displaying a warning. You can see a test on the tests folder.

• The notebooks folder renamed to examples and the v3 examples are removed because a new version will be there in some time. Too many changes could be confuse. What you think about this?
• I've added a test for the magics line %d3. Some idea for create frontend tests (maybe selenium)?
• I've added a Binderhub badge to see the examples working directly on the browser, without install even Jupyter. Also, I've fixed some little errors and updated deprecated information from README.md.

Any inconvenient, let me know.

[mondeja]

Sorry, but the code is growing a lot (now over 500 lines of code). in this new commit there are many improvements. If you don't want these changes, I will fork and continue supporting myself, I understand it.

[ResidentMario]

This is looking like a very big PR. I'll hopefully assess things this weekend, but note that it will take me some time to chew through it. =)

[ResidentMario]

OK so I started looking at this again. You're right, it's a lot of lines, very different from what I remember writing. Not a bad thing exactly, but it's difficult for me to review because of that.

Your code looks fundamentally good. Good style, good use of annotations, a few minor linting issues but nothing major. Your tests all pass on my machine.

Can you pontificate in a comment on what features that you've added in this PR? I'd like to test each of them myself in isolation. =)

[mondeja]

Of course:

• Local versions library loading: you can select online CDNJS version or local D3 loading passing a path to the file like %%d3 "d3.v5.min.js" or a online version calling with %%d3 "3.5.17". The program check if the local file exists, if not, try to load an online version and if is not valid a ValueError is raised. If any version is specified, the default will be "4.13.0" from online CDNJS. You can check all online versions using: %d3 versions" or %d3 releases. For see what version are you currently using in a notebook call %d3 version.
• Check online documentation: calling %d3 doc, the D3 API reference will be rendered in markdown format, with all local file references fixed. You can consult also documentation of every module passing their name like %d3 doc "d3-array" (this page will be rendered), and for see all D3 modules call %d3 modules.
• See online examples: I've used blockbuilder API to retrieve D3 examples cataogued by version, by user, by modules used... The examples retrieved will be in the version that you are using by default. Calling %d3 examples you will see a list with so many. Next are the basic filter for searchs (can be combined):
  • By version: %d3 examples version=3.
  • By user: %d3 examples user="mbostock".
  • By modules used: %d3 examples modules=["d3-legend", "d3-geo"].
• Generate online examples: This command uses the examples command to generate the examples retrieved in a new code cell. If you call %d3 generator (is possible using the previous filters) will be rendered a form with a text input and a button generate and the examples, both in an accordion widget (you must install ipywidgets module: pip install ipywidgets). Searching and example name, coping and pasting in the text input and clicking in generate button, a new code cell with the code of the example will be rendered.
• Generate Github gists: with the same behaviour that %d3 generator, you can load in a new code cell Github gists calling %d3 gist <gist_id>, replacing <gist_id> with a Github gist id like, for example: %d3 gist "87746f16b83cb9d5371394a001cbd772".
• General purpose utilities:
  • Verbose mode: check the code rendered internally on executed cell with %%d3 -v.

Code generator commands (%d3 generator and %d3 gist) needs more testing because some are not working yet. For example, these needing external D3 dependences like d3-geo. We need a more complex external dependencies injection (I'm working on this).

You can see a complete documentation in doc/ folder (run online here). Any questions make me known.

[ResidentMario]

Right, so this PR is too large to cover all at once. Let's break it up into several steps.

1. Can you submit a PR with just the local version library, online documentation, and verbose output features? I think I can merge that right away.
2. Let's set up a documentation microsite (like e.g. this one). The feature surface is going to be large after this set of PRs is done that users are going to need it. =)
3. Once that's done we can work on a separate PR for the online examples and GitHub gists, and adding that to the documentation.

Looking forward to 0.3.0!

[ResidentMario]

I've merged that first PR.

I've updated the documentation (and shed a good deal of weight off of it) to fit the expanded feature surface. I've had a think, and I think that the remaining features can also be handled as further additional sections to README.md, with Binder badge-links sprinkled in.

Can you re-base the remaining additional features (online examples, gists) and the test suite onto the current master in a separate PR?

The notebooks we can sort out later. I suspect this is a good time to come up with a new structure for that stuff.

[ResidentMario]

Besides the notebooks (which aren't too important), are there any other features that still need to be PR'd?