Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

jupyterlab_xkcd extension tutorial #2921

Merged
merged 23 commits into from Sep 28, 2017

Conversation

@parente
Copy link
Contributor

@parente parente commented Aug 26, 2017

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 parente force-pushed the zero-to-extension-doc branch from 3ffe4af to 1e05d39 Aug 26, 2017
@parente parente changed the title Zero to lab extension tutorial [WIP] Zero to lab extension tutorial Aug 26, 2017
@parente
Copy link
Contributor Author

@parente parente commented Aug 26, 2017

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
Copy link
Contributor Author

@parente parente commented Aug 26, 2017

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.

@parente parente changed the title [WIP] Zero to lab extension tutorial [WIP] jupyterlab_xkcd extension tutorial Sep 10, 2017
@parente parente force-pushed the zero-to-extension-doc branch from 2ac6515 to 2113f6e Sep 10, 2017
@blink1073
Copy link
Member

@blink1073 blink1073 commented Sep 11, 2017

Looking good, thanks for doing this, @parente!

@blink1073
Copy link
Member

@blink1073 blink1073 commented Sep 11, 2017

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
Copy link
Contributor Author

@parente parente commented Sep 12, 2017

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 parente force-pushed the zero-to-extension-doc branch from 637b993 to 11987d2 Sep 12, 2017
@parente parente changed the title [WIP] jupyterlab_xkcd extension tutorial jupyterlab_xkcd extension tutorial Sep 16, 2017
@parente
Copy link
Contributor Author

@parente parente commented Sep 16, 2017

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.

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

Copy link
Contributor

@jzf2101 jzf2101 Sep 18, 2017

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

Copy link
Contributor Author

@parente parente Sep 18, 2017

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.

screen shot 2017-09-18 at 2 58 47 pm

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

Copy link
Contributor

@jzf2101 jzf2101 Sep 19, 2017

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

Copy link
Contributor Author

@parente parente Sep 20, 2017

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

Copy link
Contributor Author

@parente parente Sep 21, 2017

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

Copy link
Member

@blink1073 blink1073 Sep 22, 2017

LGTM

docs/index.rst Outdated
@@ -29,6 +29,7 @@ Contents:
adding_content.md
examples.md
terminology.md
zero_to_extension.md
Copy link
Contributor

@jzf2101 jzf2101 Sep 18, 2017

should this be xkcd_extension_tutorial.md?

@parente
Copy link
Contributor Author

@parente parente commented Sep 18, 2017

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
Copy link
Member

@blink1073 blink1073 commented Sep 19, 2017

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

@parente
Copy link
Contributor Author

@parente parente commented Sep 20, 2017

@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
Copy link
Member

@ian-r-rose ian-r-rose commented Sep 20, 2017

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

@parente
Copy link
Contributor Author

@parente parente commented Sep 20, 2017

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

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

Copy link
Member

@blink1073 blink1073 Sep 22, 2017

LGTM

jupyter lab build
```

Note: The build steps may show errors about `node-gyp` and `canvas` that look scary but are harmless.
Copy link
Member

@blink1073 blink1073 Sep 22, 2017

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

};
```

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.
Copy link
Member

@blink1073 blink1073 Sep 22, 2017

bind pass -> pass?

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.
Copy link
Member

@blink1073 blink1073 Sep 22, 2017

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

Copy link
Contributor Author

@parente parente Sep 23, 2017

Updated the image.

@blink1073
Copy link
Member

@blink1073 blink1073 commented Sep 22, 2017

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

parente and others added 8 commits Sep 23, 2017
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
@parente parente force-pushed the zero-to-extension-doc branch from 95cce03 to 6c58212 Sep 23, 2017
@parente
Copy link
Contributor Author

@parente parente commented Sep 25, 2017

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
Copy link
Member

@blink1073 blink1073 commented Sep 25, 2017

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

screen shot 2017-09-21 at 9 15 48 am

@parente
Copy link
Contributor Author

@parente parente commented Sep 26, 2017

@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
Copy link
Member

@blink1073 blink1073 commented Sep 26, 2017

Worked now: 02b0277.

@jzf2101
Copy link
Contributor

@jzf2101 jzf2101 commented Sep 28, 2017

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

@blink1073
Copy link
Member

@blink1073 blink1073 commented Sep 28, 2017

In it goes, thanks so much @parente!

@blink1073 blink1073 merged commit 5325744 into jupyterlab:master Sep 28, 2017
2 checks passed
@parente
Copy link
Contributor Author

@parente parente commented Sep 28, 2017

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

@blink1073 blink1073 mentioned this pull request Oct 9, 2017
@jzf2101
Copy link
Contributor

@jzf2101 jzf2101 commented Nov 22, 2017

@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

@jasongrout jasongrout removed this from the 1.0 milestone Feb 1, 2019
@jasongrout jasongrout added this to the 0.28 milestone Feb 1, 2019
@lock lock bot locked as resolved and limited conversation to collaborators Aug 8, 2019
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

5 participants