jupyterlab_xkcd extension tutorial #2921

parente · 2017-08-26T14:47:08Z

Placeholder PR for collaboration during the JupyterCon sprint (or anytime!)

TODOs

Switch to using the CORS-enabled proxy running out of my personal AWS account so that we don't start racking up bills for https://github.com/hemanth/xkcd-imgs-heroku inadvertently. Requires updating the reference project so ...
Change the "if your code isn't working" links to point to branches in the reference repository instead of commits so that we can rev the tutorial over time.
Decide if the reference repo should move to jupyterlab/jupyterlab_xkcd.

parente · 2017-08-26T17:46:34Z

Note to whoever is watching: these are just notes for now. Might turn into an executable notebook for steps beyond the initial conda environment setup.

parente · 2017-08-26T19:46:09Z

cc @mkery, nice meeting you. I've given you commit / push permissions on the branch for this PR. I don't know where it's going to wind-up, but feel free to hack on it if you'd like.

blink1073 · 2017-09-11T16:41:56Z

Looking good, thanks for doing this, @parente!

blink1073 · 2017-09-11T16:43:04Z

Note that we will be turning this into a notebook so we can test it on CI (doesn't have to be in this PR).

parente · 2017-09-12T00:31:01Z

Note that we will be turning this into a notebook so we can test it on CI (doesn't have to be in this PR).

@bollwyvl mentioned that at the sprints. I'm for it. Just wanted to focus on getting my feet under me to start.

parente · 2017-09-16T02:53:48Z

OK. I think I'm done with my draft. It's a bit lengthy (GitHub says the md file is too long to show by default in the diff view, 🙊 ) and that's intentional. It lays out all of the code changes, terminal commands, and browser actions for the reader, and walks through building https://github.com/parente/jupyterlab_xkcd commit by commit.

We can move that reference version to jupyterlab/jupyterlab_xkcd if desired. Let me know.

jzf2101 · 2017-09-18T17:34:46Z

docs/xkcd_extension_tutorial.md

@@ -0,0 +1,653 @@
+# Let's Make an xkcd JupyterLab Extension
+


This document is rather long. Could you consider including a table of contents with section links? Or perhaps breaking up the document?

I totally agree. I was thinking the one in the left sidebar of the alabaster theme is a good start since it links to all of the section headings.

It does scroll with the page, however, so it's still somewhat annoying to jump around. I'm open to other ideas.

This would work if sections were grouped into higher level groupings eg Installation and Initialize Extension With The Cookiecutter

Sure. I'll take a pass at them on the next update.

How about these, where only the # and ## level headings appears in the table of contents:

# Let's Make an xkcd JupyterLab Extension ## Setup a development environment ### Install conda using miniconda ### Install NodeJS, JupyterLab, etc. in a conda environment ## Create an extension project ### Initialize the project from a cookiecutter ### Build and link the extension for development ### See the initial extension in action ### Commit what you have to git ## Add an xkcd widget ### Show an empty panel ### Show a comic in the panel ## Improve the widget behavior ### Center the comic and add attribution ### Show a new comic on demand ### Restore panel state when the browser refreshes ## Publish your extension to npmjs.org ## Learn more

jzf2101 · 2017-09-18T17:38:05Z

docs/index.rst

@@ -29,6 +29,7 @@ Contents:
   adding_content.md
   examples.md
   terminology.md
+   zero_to_extension.md


should this be xkcd_extension_tutorial.md?

parente · 2017-09-18T19:13:33Z

Added a list of TODOs to the PR description. I'd like to handle these before the PR merges, in addition to feedback from reviewers.

blink1073 · 2017-09-19T12:54:03Z

@parente, 👍 to move the repo to this org.

parente · 2017-09-20T01:10:12Z

@blink1073 will do. I'll do that soon and update the various links in the tutorial.

Should I push a release of it on npm under @jupyterlab/jupyterlab_xkcd instead of my personal space? If so, I'll need access or someone to do it.

ian-r-rose · 2017-09-20T01:14:43Z

@parente If you give me your npm user name I can add you to the org.

parente · 2017-09-20T01:28:18Z

@ian-r-rose You got it first try: parente 😄

blink1073 · 2017-09-22T19:31:59Z

docs/xkcd_extension_tutorial.md

@@ -0,0 +1,653 @@
+# Let's Make an xkcd JupyterLab Extension
+


blink1073 · 2017-09-22T19:34:27Z

docs/xkcd_extension_tutorial.md

+jupyter lab build
+```
+
+Note: The build steps may show errors about `node-gyp` and `canvas` that look scary but are harmless.


I think we can remove this since the errors won't be there in the next release.

blink1073 · 2017-09-22T19:36:14Z

docs/xkcd_extension_tutorial.md

+};
+```
+
+The `requires` attribute states that your plugin needs an object that implements the `ICommandPalette` interface when it starts. JupyterLab will bind pass an instance of `ICommandPalette` as the second parameter of `activate` in order to satisfy this requirement. Defining `palette: ICommandPalette` makes this instance available to your code in that function. The second `console.log` line exists only so that you can immediately check that your changes work.


bind pass -> pass?

blink1073 · 2017-09-22T19:42:12Z

docs/xkcd_extension_tutorial.md

+npm publish --access=public
+```
+
+Check that your package appears on the npm website. You can either search for it from the homepage or visit https://www.npmjs.com/package/@your-username/jupyterlab_xkcd directly. If it doesn't appear, make sure you've updated the package name properly in the `package.json` and run the npm command correctly. Compare your work with the state of the reference project at the [06-prepare-to-publish tag](https://github.com/jupyterlab/jupyterlab_xkcd/tree/06-prepare-to-publish) for further debugging.


Should this be updated to show @jupyterlab/xkcd-extension?

Updated the image.

blink1073 · 2017-09-22T19:43:34Z

@parente, do you mind also rebasing to pick up the build fix from #3020?

Open for early feedback during the sprint

* Add screenshot * Add git * Avoid PATH mods in conda steps (and come closer to what conda 4.4 supports)

* Screenshot of current progress * Rename completed screenshot * Link to reference impl for troubleshooting

Instead of bombarding someone else's heroku app instance

* Fix links so that they render * Use tags instead of commits so we can move them around later.

Also match current package naming convention and use @jupyterlab/xkcd-extension

parente · 2017-09-25T16:42:19Z

I rebased but it looks like travis is still failing. Let me know if there's anything else you'd like me to do or change before merge.

blink1073 · 2017-09-25T17:07:03Z

@parente, have you checked this box in this PR? I tried pushing a commit but it didn't go through:

parente · 2017-09-26T16:08:50Z

@blink1073 I do have that checked. I've never had much success with that feature. I can grant you read/write access to my PR branch in my fork.

blink1073 · 2017-09-26T17:38:51Z

Worked now: 02b0277.

jzf2101 · 2017-09-28T19:08:11Z

@parente would you be interested in turning this into a blogpost on the medium?

blink1073 · 2017-09-28T19:45:56Z

In it goes, thanks so much @parente!

parente · 2017-09-28T21:24:42Z

@jzf2101 Sure. Are you thinking of it as a teaser that links to the full thing or a repost of the whole doc?

jzf2101 · 2017-11-22T14:58:44Z

@parente i was thinking like a 5 minute read version of this that explains the high level steps but refers to the documentation you wrote for further details

parente force-pushed the zero-to-extension-doc branch from 3ffe4af to 1e05d39 Compare August 26, 2017 14:48

parente changed the title ~~Zero to lab extension tutorial~~ [WIP] Zero to lab extension tutorial Aug 26, 2017

parente changed the title ~~[WIP] Zero to lab extension tutorial~~ [WIP] jupyterlab_xkcd extension tutorial Sep 10, 2017

parente force-pushed the zero-to-extension-doc branch from 2ac6515 to 2113f6e Compare September 10, 2017 18:48

parente force-pushed the zero-to-extension-doc branch from 637b993 to 11987d2 Compare September 12, 2017 01:35

parente changed the title ~~[WIP] jupyterlab_xkcd extension tutorial~~ jupyterlab_xkcd extension tutorial Sep 16, 2017

jzf2101 reviewed Sep 18, 2017

View reviewed changes

jzf2101 mentioned this pull request Sep 18, 2017

Reference Documenation from XKCD PR? jupyterlab/mimerender-cookiecutter-ts#4

Closed

jzf2101 reviewed Sep 18, 2017

View reviewed changes

blink1073 reviewed Sep 22, 2017

View reviewed changes

parente and others added 8 commits September 22, 2017 23:25

Start a placeholder with a goal for the doc

21c063a

Open for early feedback during the sprint

Add conda, cookiecutter steps

6151982

Steps up to running the cookiecutter example in lab

a68c825

New intro, new purpose, moar fun!

38eb150

Refine setup steps

4c1e480

* Add screenshot * Add git * Avoid PATH mods in conda steps (and come closer to what conda 4.4 supports)

Fix grammar, add dev outline sections

53e0427

Start of the command section

39590d5

Finish the command section

d7cce07

* Screenshot of current progress * Rename completed screenshot * Link to reference impl for troubleshooting

parente added 11 commits September 22, 2017 23:25

Add section on refactoring and comic refresh

3822bdd

Add section about layout save/restore

0e2673f

Fix typo

acf78ab

Final sections about npm, typo fixes

6fdcf64

Fix ToC document name

7e3f5f4

Use an AWS Lambda function for a random xkcd

3d8a301

Instead of bombarding someone else's heroku app instance

Link to tags in the reference project

5b9f0dd

* Fix links so that they render * Use tags instead of commits so we can move them around later.

Fix link typo

cfcbe6b

More section nesting, xkcd typo fixes

4e04f84

Update links, package for jupyterlab org

c1894fb

Also match current package naming convention and use @jupyterlab/xkcd-extension

Update npmjs image, address text comments

6c58212

parente force-pushed the zero-to-extension-doc branch from 95cce03 to 6c58212 Compare September 23, 2017 03:25

Link and formatting cleanup

02b0277

blink1073 added this to the 1.0 milestone Sep 25, 2017

blink1073 added tag:Extensions documentation labels Sep 25, 2017

blink1073 merged commit 5325744 into jupyterlab:master Sep 28, 2017

blink1073 mentioned this pull request Oct 9, 2017

Release 0.28 #3076

Closed

jasongrout modified the milestones: 1.0, 0.28 Feb 1, 2019

lock bot added the status:resolved-locked Closed issues are locked after 30 days inactivity. Please open a new issue for related discussion. label Aug 8, 2019

lock bot locked as resolved and limited conversation to collaborators Aug 8, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

jupyterlab_xkcd extension tutorial #2921

jupyterlab_xkcd extension tutorial #2921

parente commented Aug 26, 2017 •

edited

parente commented Aug 26, 2017

parente commented Aug 26, 2017

blink1073 commented Sep 11, 2017

blink1073 commented Sep 11, 2017

parente commented Sep 12, 2017

parente commented Sep 16, 2017 •

edited

jzf2101 Sep 18, 2017

parente Sep 18, 2017

jzf2101 Sep 19, 2017 •

edited

parente Sep 20, 2017

parente Sep 21, 2017

blink1073 Sep 22, 2017

jzf2101 Sep 18, 2017 •

edited

parente commented Sep 18, 2017

blink1073 commented Sep 19, 2017

parente commented Sep 20, 2017

ian-r-rose commented Sep 20, 2017

parente commented Sep 20, 2017 •

edited

blink1073 Sep 22, 2017

blink1073 Sep 22, 2017

blink1073 Sep 22, 2017

blink1073 Sep 22, 2017

parente Sep 23, 2017

blink1073 commented Sep 22, 2017

parente commented Sep 25, 2017

blink1073 commented Sep 25, 2017

parente commented Sep 26, 2017

blink1073 commented Sep 26, 2017

jzf2101 commented Sep 28, 2017

blink1073 commented Sep 28, 2017

parente commented Sep 28, 2017

jzf2101 commented Nov 22, 2017

jupyterlab_xkcd extension tutorial #2921

jupyterlab_xkcd extension tutorial #2921

Conversation

parente commented Aug 26, 2017 • edited

parente commented Aug 26, 2017

parente commented Aug 26, 2017

blink1073 commented Sep 11, 2017

blink1073 commented Sep 11, 2017

parente commented Sep 12, 2017

parente commented Sep 16, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jzf2101 Sep 19, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jzf2101 Sep 18, 2017 • edited

Choose a reason for hiding this comment

parente commented Sep 18, 2017

blink1073 commented Sep 19, 2017

parente commented Sep 20, 2017

ian-r-rose commented Sep 20, 2017

parente commented Sep 20, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

blink1073 commented Sep 22, 2017

parente commented Sep 25, 2017

blink1073 commented Sep 25, 2017

parente commented Sep 26, 2017

blink1073 commented Sep 26, 2017

jzf2101 commented Sep 28, 2017

blink1073 commented Sep 28, 2017

parente commented Sep 28, 2017

jzf2101 commented Nov 22, 2017

parente commented Aug 26, 2017 •

edited

parente commented Sep 16, 2017 •

edited

jzf2101 Sep 19, 2017 •

edited

jzf2101 Sep 18, 2017 •

edited

parente commented Sep 20, 2017 •

edited