diff --git a/.circleci/config.yml b/.circleci/config.yml deleted file mode 100644 index e12c7e5b..00000000 --- a/.circleci/config.yml +++ /dev/null @@ -1,65 +0,0 @@ -version: 2.1 -jobs: - build_docs: - docker: - - image: circleci/python:3.6-stretch - steps: - - build_site - - store_artifacts: - path: docs/_build/html/ - destination: html - - push_docs: - docker: - - image: circleci/python:3.6-stretch - steps: - # Add deployment key fingerprint for CircleCI to use for a push - - add_ssh_keys: - fingerprints: - # The SSH key fingerprint - - "c5:70:b9:1b:9a:cf:e3:88:25:9f:33:8e:ee:09:76:9f" - - - build_site - - - run: - name: Pushing documentation to gh-pages - command: | - pip install --user ghp-import - ghp-import --no-jekyll --push --message "Update documentation [skip ci]" docs/_build/html - -workflows: - version: 2 - default: - jobs: - - build_docs - - push_docs: - filters: # using regex filters requires the entire branch to match - branches: - only: # only branches matching the below regex filters will run - - main - -commands: - build_site: - description: "Build the site with sphinx" - steps: - # Get our data and merge with upstream - - run: sudo apt-get update - - checkout - # Python env - - run: echo "export PATH=~/.local/bin:$PATH" >> $BASH_ENV - - - restore_cache: - keys: - - cache-pip - - run: pip install --user -r docs/doc-requirements.txt - - save_cache: - key: cache-pip - paths: - - ~/.cache/pip - - # Build the docs - - run: - name: Build docs to store - command: | - cd docs - make html diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..fb83a15d --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,69 @@ +# This is a GitHub workflow defining a set of jobs with a set of steps. +# ref: https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions +# +name: Documentation + +on: + pull_request: + paths: + - "docs/**" + - "**/docs.yml" + push: + paths: + - "docs/**" + - "**/docs.yml" + branches-ignore: + - "dependabot/**" + - "pre-commit-ci-update-config" + tags: ["**"] + workflow_dispatch: + +env: + SPHINXOPTS: --color + +jobs: + linkcheck: + runs-on: ubuntu-20.04 + + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-python@v2 + with: + python-version: '3.10' + + - name: Install dependencies + run: | + pip install -r docs/doc-requirements.txt + + - name: make linkcheck (Verifies documentation links work) + run: | + cd docs + make linkcheck + + build-and-publish: + runs-on: ubuntu-20.04 + + permissions: + # required to push to the gh-pages branch + contents: write + + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-python@v2 + with: + python-version: '3.10' + + - name: Install dependencies + run: | + pip install -r docs/doc-requirements.txt + + - name: make html (Builds documentation) + run: | + cd docs + make html + + - name: Publish to GitHub Pages + if: github.ref == 'refs/heads/main' + run: | + pip install ghp-import + ghp-import --no-jekyll --push --message "Update documentation [skip ci]" docs/_build/html diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 3dfe659f..21e70ced 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -1,11 +1,23 @@ -# Build releases and (on tags) publish to PyPI +# This is a GitHub workflow defining a set of jobs with a set of steps. +# ref: https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions +# +# Build releases and publish to PyPI if a tag is pushed name: Release -# always build releases (to make sure wheel-building works) -# but only publish to PyPI on tags on: - push: pull_request: + paths-ignore: + - "docs/**" + - "**/docs.yml" + push: + paths-ignore: + - "docs/**" + - "**/docs.yml" + branches-ignore: + - "dependabot/**" + - "pre-commit-ci-update-config" + tags: ["**"] + workflow_dispatch: jobs: build-release: @@ -14,7 +26,10 @@ jobs: - uses: actions/checkout@v2 - uses: actions/setup-python@v2 with: - python-version: 3.8 + python-version: "3.8" + - uses: actions/setup-node@v2 + with: + node-version: "16" - name: install build package run: | diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 89168d61..4b5eec82 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -1,54 +1,57 @@ # This is a GitHub workflow defining a set of jobs with a set of steps. -# ref: https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions +# ref: https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions # name: Tests on: pull_request: + paths-ignore: + - "docs/**" + - "**/docs.yml" push: + paths-ignore: + - "docs/**" + - "**/docs.yml" + branches-ignore: + - "dependabot/**" + - "pre-commit-ci-update-config" + tags: ["**"] workflow_dispatch: jobs: test: - runs-on: ubuntu-20.04 timeout-minutes: 10 + strategy: + fail-fast: false + matrix: + python-version: ["3.7", "3.8", "3.9", "3.10"] + node-version: ["16"] + steps: - uses: actions/checkout@v2 + - uses: actions/setup-python@v2 + with: + python-version: "${{ matrix.python-version }}" + - uses: actions/setup-node@v2 + with: + node-version: "${{ matrix.node-version }}" - name: Run webpack to build static assets run: | npm install npm run webpack - - name: Install Python - uses: actions/setup-python@v2 - with: - python-version: '3.8' - - # DISABLED: Since we don't pin our dependencies in dev-requirements.txt - # and only refresh the cache when it changes, we end up with a - # cache that remains for too long and cause failures. Due to - # this, it has been disabled. - # - # - name: Cache pip dependencies - # uses: actions/cache@v2 - # with: - # path: ~/.cache/pip - # # Look to see if there is a cache hit for the corresponding requirements file - # key: ${{ runner.os }}-pip-${{ hashFiles('*requirements.txt') }} - # restore-keys: | - # ${{ runner.os }}-pip- - - name: Install dependencies run: | pip install -r dev-requirements.txt + pip install . + pip freeze - name: Run flake8 linter run: flake8 - name: Run tests run: | - pip install . pytest --verbose --maxfail=2 --color=yes --cov nbgitpuller diff --git a/CHANGELOG.md b/CHANGELOG.md index 363cf279..3c762452 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,45 @@ ## 1.0 +### 1.1.0 + +([full changelog](https://github.com/jupyterhub/nbgitpuller/compare/1.0.2...1.1.0)) + +#### Enhancements made + +- Add retrolab support to link generator [#225](https://github.com/jupyterhub/nbgitpuller/pull/225) ([@yuvipanda](https://github.com/yuvipanda)) + +#### Bugs fixed + +- Fix sync problems after deleting files [#257](https://github.com/jupyterhub/nbgitpuller/pull/257) ([@jdmansour](https://github.com/jdmansour)) +- Use our own jinja2 template loader [#255](https://github.com/jupyterhub/nbgitpuller/pull/255) ([@yuvipanda](https://github.com/yuvipanda)) + +#### Maintenance and upkeep improvements + +- Remove binder folder with link_generator.ipynb [#249](https://github.com/jupyterhub/nbgitpuller/pull/249) ([@consideRatio](https://github.com/consideRatio)) +- Use async/await instead of gen.coroutine/yield [#246](https://github.com/jupyterhub/nbgitpuller/pull/246) ([@consideRatio](https://github.com/consideRatio)) + +#### Documentation improvements + +- Fix note format [#250](https://github.com/jupyterhub/nbgitpuller/pull/250) ([@brian-rose](https://github.com/brian-rose)) +- docs: adds docstrings (refactor: rename local parameter) [#242](https://github.com/jupyterhub/nbgitpuller/pull/242) ([@consideRatio](https://github.com/consideRatio)) +- DOC: Add link gen. screenshot, update example gif [#238](https://github.com/jupyterhub/nbgitpuller/pull/238) ([@consideRatio](https://github.com/consideRatio)) +- Update docs and remove unnecessary Sphinx configuration files [#237](https://github.com/jupyterhub/nbgitpuller/pull/237) ([@choldgraf](https://github.com/choldgraf)) +- Point people to the browser extension [#231](https://github.com/jupyterhub/nbgitpuller/pull/231) ([@yuvipanda](https://github.com/yuvipanda)) + +#### Other merged PRs + +- ci: test against python 3.7-3.10 [#245](https://github.com/jupyterhub/nbgitpuller/pull/245) ([@consideRatio](https://github.com/consideRatio)) +- Build docs using GitHub Actions, add linkcheck, and small tweaks to CI system [#232](https://github.com/jupyterhub/nbgitpuller/pull/232) ([@yuvipanda](https://github.com/yuvipanda)) +- Fix conf.py to work on newer versions of sphinx [#226](https://github.com/jupyterhub/nbgitpuller/pull/226) ([@yuvipanda](https://github.com/yuvipanda)) +- npm: auto-rebuild dist if js changed [#222](https://github.com/jupyterhub/nbgitpuller/pull/222) ([@manics](https://github.com/manics)) + +#### Contributors to this release + +([GitHub contributors page for this release](https://github.com/jupyterhub/nbgitpuller/graphs/contributors?from=2021-09-02&to=2022-03-18&type=c)) + +[@akhmerov](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3Aakhmerov+updated%3A2021-09-02..2022-03-18&type=Issues) | [@brian-rose](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3Abrian-rose+updated%3A2021-09-02..2022-03-18&type=Issues) | [@choldgraf](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3Acholdgraf+updated%3A2021-09-02..2022-03-18&type=Issues) | [@consideRatio](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3AconsideRatio+updated%3A2021-09-02..2022-03-18&type=Issues) | [@jameshowison](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3Ajameshowison+updated%3A2021-09-02..2022-03-18&type=Issues) | [@jdmansour](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3Ajdmansour+updated%3A2021-09-02..2022-03-18&type=Issues) | [@manics](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3Amanics+updated%3A2021-09-02..2022-03-18&type=Issues) | [@ryanlovett](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3Aryanlovett+updated%3A2021-09-02..2022-03-18&type=Issues) | [@welcome](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3Awelcome+updated%3A2021-09-02..2022-03-18&type=Issues) | [@yuvipanda](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3Ayuvipanda+updated%3A2021-09-02..2022-03-18&type=Issues) | [@Zsailer](https://github.com/search?q=repo%3Ajupyterhub%2Fnbgitpuller+involves%3AZsailer+updated%3A2021-09-02..2022-03-18&type=Issues) + + ### 1.0.2 - 2021-09-03 A release to fix an issue that stopped us from publishing nbgitpuller on diff --git a/README.md b/README.md index 2fa08a4b..ff7175dc 100644 --- a/README.md +++ b/README.md @@ -25,4 +25,15 @@ pip install nbgitpuller ## Example -![](https://raw.githubusercontent.com/jupyterhub/nbgitpuller/v0.8.0/docs/_static/nbpuller.gif) + +This example shows how to use the [nbgitpuller link generator](https://jupyterhub.github.io/nbgitpuller/link) +to create an nbgitpuller link, which a user then clicks. + +1. The [nbgitpuller link generator GUI](https://jupyterhub.github.io/nbgitpuller/link) is used to create a + link. + + ![](https://raw.githubusercontent.com/jupyterhub/nbgitpuller/9f380a933335f0f069b6e2f9965ed78c3abcce7a/docs/_static/nbgitpuller-link-generator.png) + +2. This link is clicked, and the content is pulled into a live Jupyter session. + + ![](https://raw.githubusercontent.com/jupyterhub/nbgitpuller/9f380a933335f0f069b6e2f9965ed78c3abcce7a/docs/_static/nbgitpuller-demo.gif) diff --git a/binder/link_generator.ipynb b/binder/link_generator.ipynb deleted file mode 100644 index fea897ef..00000000 --- a/binder/link_generator.ipynb +++ /dev/null @@ -1,164 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Generate `nbgitpuller` links for your JupyterHub\n", - "\n", - "When users click an `nbgitpuller` link pointing to your JupyterHub,\n", - "\n", - "1. They are asked to log in to the JupyterHub if they have not already\n", - "2. The git repository referred to in the nbgitpuller link is made up to date in their home directory (keeping local changes if there are merge conflicts)\n", - "3. They are shown the specific notebook / directory referred to in the nbgitpuller link.\n", - "\n", - "This is a great way to distribute materials to students.\n", - "\n", - "# Generate `nbgitpuller` links for your JupyterHub\n", - "\n", - "## Sequence of events when users click an `nbgitpuller` link pointing to your JupyterHub,\n", - "\n", - "1. They are asked to log in to the JupyterHub if they have not already\n", - "2. The git repository referred to in the nbgitpuller link is made up to date in their home directory (keeping local changes if there are merge conflicts)\n", - "3. They are shown the specific notebook / directory referred to in the nbgitpuller link.\n", - "\n", - "This is a great way to distribute materials to students.\n", - "\n", - "## Canvas LMS: Assignment Links vs Custom Fields\n", - "\n", - "The Canvas LMS expects the assignment link to include URL encoded parameters since the request is sent to the External Tool as a POST request (in this case JupyterHub is the External Tool). However, all characters (even those considered safe) after the domain and `next=` part should be URL encoded, such as the `/`, `&`, and `=` characters.\n", - "\n", - "The `Custom Fields` text box in the App -> Settings section, on the other hand, does not expect all characters to be URL encoded. The `/` characters that are assigned as part of the query parameter values should be encoded, but not the `&` and `=` characters.\n", - "\n", - "## Usage\n", - "\n", - "- **Assignment Link**: creates a string value which represents an `Assignment` link by toggling the check box next to the `is_assignment_link` label. If unchecked, the tool will create a string to add to the Custom Field section.\n", - "- **Jupyter Lab Link**: creates a string value which redirects the user to a `Jupyter Lab` workspace instead of the `Jupyter Classic` workspace.\n", - "- **LTI Launches**: adds the route associated to the LTI 1.1 login handler. If disabled, it is assumed that the user is using the default authentication class bound to the root of the `domain_url` value.\n", - "- **Default Values**: to avoid having to enter the same values in the widget's text fields on a repetitive basis, add the string values to the function's parameters. For example, the `branch` parameter defaults to `master`." - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "metadata": {}, - "outputs": [ - { - "output_type": "display_data", - "data": { - "text/plain": "'https://my.hub.com/hub/lti/launch?next=%2Fuser-redirect%2Fgit-pull?repo%3D%26branch%3Dmaster%26urlpath%3Dlab%252Ftree%252F.%252F%253Fautodecode'" - }, - "metadata": {} - } - ], - "source": [ - "import os\n", - "from ipywidgets import interact\n", - "from urllib.parse import urlunparse, urlparse, urlencode, parse_qs, parse_qsl, quote\n", - "from IPython.display import Markdown\n", - "\n", - "\n", - "@interact\n", - "def make_launch_link(is_assignment_link=True, is_jupyterlab=True, is_lti11=True, branch='master', hub_url='https://my.hub.com', repo_url='', urlpath=''):\n", - " \"\"\"\n", - " Generate a launch request which clones and merges source files from a git-based\n", - " repository.\n", - "\n", - " Args:\n", - " is_assignment_link (bool): set to True to create a full assignment link, defaults to True.\n", - " is_jupyterlab (bool): set to True to launch Jupyter Lab workspaces, defaults to True.\n", - " is_lti11 (bool): set to True to initiate launch requests with the LTI 1.1 standard.\n", - " branch (str): git repo branch\n", - " hub_url (str): full hub url which needs to include scheme (http or https) and netloc (full domain).\n", - " repo_url (str): full git repo url which needs to include scheme (http or https), netloc (full domain) and path.\n", - " url_path (str): a path to redirect users to after the workspace has successfully spawned (started).\n", - "\n", - " Returns:\n", - " An interactive IPython.display.Markdown object.\n", - " \"\"\"\n", - "\n", - " # Parse the query to its constituent parts\n", - " domain_scheme, domain_netloc, domain_path, domain_params, domain_query_str, domain_fragment = urlparse(hub_url.strip())\n", - " \n", - " repo_scheme, repo_netloc, repo_path, repo_params, repo_query_str, repo_fragment = urlparse(repo_url.strip())\n", - " folder_from_repo_url_path = os.path.basename(os.path.normpath(repo_path))\n", - " \n", - " # Make sure the path doesn't contain multiple slashes\n", - " if not domain_path.endswith('/'):\n", - " domain_path += '/'\n", - " domain_path += 'user-redirect/git-pull'\n", - " \n", - " # With Canvas using LTI 11 Assignment launch requests all characters after the netloc are considered unsafe.\n", - " # When adding custom parameters within the App Settings -> Custom Fields section, only items after the \n", - " path_encoded = ''\n", - " if is_assignment_link:\n", - " path_encoded = quote(domain_path, safe='')\n", - " else:\n", - " path_encoded = quote(domain_path)\n", - "\n", - " path_redirect_url = f'next={path_encoded}'\n", - " if is_lti11:\n", - " assignment_link_path = f'/hub/lti/launch?next={path_encoded}'\n", - " else:\n", - " assignment_link_path = f'/hub?next={path_encoded}'\n", - " \n", - " # Create a tuple of query params from original domain link\n", - " query_params_from_hub_url = parse_qsl(domain_query_str, keep_blank_values=True)\n", - " \n", - " # Set path based on whether or not the user would like to spawn JupyterLab or Jupyter Classic\n", - " urlpath_workspace = ''\n", - " if is_jupyterlab:\n", - " urlpath_workspace = f'lab/tree/{folder_from_repo_url_path}/{urlpath}?autodecode'\n", - " else:\n", - " urlpath_workspace = f'tree/{folder_from_repo_url_path}/{urlpath}'\n", - " \n", - " # Create a tuple of query params for git functionality. Check whether or not we want to launch with\n", - " # jupyterlab to add additional items to the path.\n", - " query_params_for_git = [('repo', repo_url), ('branch', branch), ('urlpath', urlpath_workspace)]\n", - " \n", - " # Merge query params into one list of tuples\n", - " query_params_all = query_params_from_hub_url + query_params_for_git\n", - " \n", - " # First build urlencoded query params where the &, =, and / are considered safe. Then, percent encode\n", - " # all characters.\n", - " encoded_query_params = urlencode(query_params_all)\n", - " encoded_query_params_without_safe_chars = quote(urlencode(query_params_all), safe='')\n", - " \n", - " assignment_link_url = urlunparse((domain_scheme, domain_netloc, assignment_link_path, domain_params, encoded_query_params_without_safe_chars, domain_fragment))\n", - " path_url = urlunparse(('', '', path_redirect_url, domain_params, encoded_query_params, domain_fragment))\n", - " \n", - " if is_assignment_link:\n", - " return assignment_link_url\n", - " return path_url" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.8.1-final" - } - }, - "nbformat": 4, - "nbformat_minor": 2 -} diff --git a/binder/postBuild b/binder/postBuild deleted file mode 100644 index 82984087..00000000 --- a/binder/postBuild +++ /dev/null @@ -1,3 +0,0 @@ -#!/bin/bash -jupyter nbextension enable --py --sys-prefix appmode -jupyter serverextension enable --py --sys-prefix appmode \ No newline at end of file diff --git a/binder/requirements.txt b/binder/requirements.txt deleted file mode 100644 index 87cc5638..00000000 --- a/binder/requirements.txt +++ /dev/null @@ -1,2 +0,0 @@ -ipywidgets -appmode \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile index 9764015b..e74b0547 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,20 +1,38 @@ -# Minimal makefile for Sphinx documentation -# +# Makefile for Sphinx documentation generated by sphinx-quickstart +# ---------------------------------------------------------------------------- -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SPHINXPROJ = Binder +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build SOURCEDIR = . BUILDDIR = _build # Put it first so that "make" without argument is like "make help". help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) .PHONY: help Makefile # Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +# "make mode" option. %: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) + + +# Manually added commands +# ---------------------------------------------------------------------------- + +# For local development: +# - builds and rebuilds html on changes to source +# - starts a livereload enabled webserver and opens up a browser +devenv: + sphinx-autobuild -b html --open-browser "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) + +# For local development and CI: +# - verifies that links are valid +linkcheck: + $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)/linkcheck" $(SPHINXOPTS) + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." diff --git a/docs/_static/link_gen/link.js b/docs/_static/link_gen/link.js index dd371c81..f5e11e2d 100644 --- a/docs/_static/link_gen/link.js +++ b/docs/_static/link_gen/link.js @@ -80,6 +80,10 @@ var apps = { title: 'Classic Notebook', generateUrlPath: function (path) { return 'tree/' + path; }, }, + retrolab: { + title: 'RetroLab', + generateUrlPath: function (path) { return 'retro/tree/' + path; }, + }, jupyterlab: { title: 'JupyterLab', generateUrlPath: function (path) { return 'lab/tree/' + path; } diff --git a/docs/_static/nbgitpuller-demo.gif b/docs/_static/nbgitpuller-demo.gif new file mode 100644 index 00000000..10e8d125 Binary files /dev/null and b/docs/_static/nbgitpuller-demo.gif differ diff --git a/docs/_static/nbgitpuller-link-generator.png b/docs/_static/nbgitpuller-link-generator.png new file mode 100644 index 00000000..0e686bbb Binary files /dev/null and b/docs/_static/nbgitpuller-link-generator.png differ diff --git a/docs/_static/nbpuller.gif b/docs/_static/nbpuller.gif deleted file mode 100644 index 9ccbe76d..00000000 Binary files a/docs/_static/nbpuller.gif and /dev/null differ diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html deleted file mode 100644 index 5598856a..00000000 --- a/docs/_templates/layout.html +++ /dev/null @@ -1,14 +0,0 @@ -{%- extends "sphinx_book_theme/layout.html" %} - - -{% block extrahead %} -{% if pagename == 'link' %} - -{% endif %} -{{ super() }} -{% endblock %} diff --git a/docs/conf.py b/docs/conf.py index 66fb9cb2..baa0be9a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -5,8 +5,7 @@ def setup(app): - app.add_stylesheet("custom.css") - app.add_javascript("link_gen/link.js") + app.add_js_file("link_gen/link.js") # -- General configuration ------------------------------------------------ @@ -24,7 +23,7 @@ def setup(app): ] # Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] +templates_path = [] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: @@ -37,7 +36,7 @@ def setup(app): # General information about the project. project = "nbgitpuller" -copyright = "2017, The nbgitpuller Team" +copyright = "2021, The nbgitpuller Team" author = "The nbgitpuller Team" # The version info for the project you're documenting, acts as replacement for @@ -61,8 +60,6 @@ def setup(app): # This patterns also effect to html_static_path and html_extra_path exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] -html_sidebars = {"**": ["globaltoc.html", "relations.html", "searchbox.html"]} - # The name of the Pygments (syntax highlighting) style to use. pygments_style = "sphinx" @@ -75,6 +72,7 @@ def setup(app): # a list of builtin themes. # html_theme = "sphinx_book_theme" +html_title = "nbgitpuller documentation" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..f1a649d9 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,72 @@ +# nbgitpuller + +`nbgitpuller` lets you distribute content to a Jupyter user via the click of a button! +This allows your users to focus on the content without needing to understand `git` +or other version control machinery. + +`nbgitpuller` provides {ref}`automatic, opinioned conflict resolution ` +by using `git` under the hood. +It is commonly used to distribute content to multiple users of a JupyterHub, though it works just fine on an individual person's computer, if they have Jupyter installed. + +Here's an example of `nbgitpuller` in action: + +1. The [nbgitpuller link + generator](https://jupyterhub.github.io/nbgitpuller/link) is used to create a + link. + + ```{image} _static/nbgitpuller-link-generator.png + ``` + +2. A user clicks the link, and the content is pulled into a live Jupyter session. + + ```{image} _static/nbgitpuller-demo.gif + ``` + +## Use `nbgitpuller` + +See [](use.md) for information about how to use `nbgitpuller`. +Here's a short overview: + +1. Ensure your user has `nbgitpuller` installed. This is commonly done by installing it for all users of a JupyterHub. See [the installation instructions](install.rst) for more information. +2. Create an "`nbgitpuller` link" which points to the content you'd like to distribute (e.g., a Jupyter Notebook in a GitHub repository). +3. Tell your user to click the link, and `nbgitpuller` will automatically pull in the content to their file system. + +### Generate an nbgitpuller link + +There are several ways to generate an `nbgitpuller` link. +The two easiest ways to do so are: +- Via a browser extension to generate links directly from your repository ([Chrome extension](https://chrome.google.com/webstore/detail/nbgitpuller-link-generato/hpdbdpklpmppnoibabdkkhnfhkkehgnc), [Firefox extension](https://addons.mozilla.org/en-US/firefox/addon/nbgitpuller-link-generator/?utm_source=addons.mozilla.org&utm_medium=referral&utm_content=search) +- Via a GUI web-app [at `nbgitpuller.link`](http://nbgitpuller.link) + +Fore more information about generating nbgitpuller links, see [](use.md). + +### When to use `nbgitpuller` + +Use nbgitpuller when: + +1. You want an easy way to distribute content (notebooks, markdown files, etc) to Jupyter users without requiring them to use `git`. +2. You have an alternative method for *collecting* content from your users, as `nbgitpuller` does not "push", it only "pulls". + +You should **not** use nbgitpuller when: + +1. Users want to **push** to a `git` repository that has your content. + In this case, you should instruct them to just use `git` directly, + since the assumptions and design of nbgitpuller will surprise you in + unexpected ways if you are pushing with git but pulling with nbgitpuller. +2. Users want to perform **manual git operations** locally. + Mixing manual git operations + automatic nbgitpuller operations will + cause unwelcome surprises. + +## Full Contents + +```{toctree} +:maxdepth: 2 + +install +use +contributing +topic/automatic-merging +topic/url-options +topic/repo-best-practices +link +``` diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index ef65d01f..00000000 --- a/docs/index.rst +++ /dev/null @@ -1,96 +0,0 @@ -=========== -nbgitpuller -=========== - -``nbgitpuller`` lets you distribute content in a git repository to your -students by having them click a simple link. :ref:`Automatic, opinioned -conflict resolution ` ensures that your students are -never exposed to ``git`` directly. It is primarily used with a JupyterHub, -but can also work on students' local laptops. - -.. image:: _static/nbpuller.gif - -When to use nbgitpuller? -======================== - -You should use nbgitpuller when: - -#. You are running a JupyterHub for a class & want an easy way to distribute - materials to your students without them having to understand what git is. -#. You have a different out of band method for collecting completed - assignments / notebooks from students, since they can not just 'push it - back' via git. - -You should **not** use nbgitpuller when: - -#. You are an instructor using a JupyterHub / running notebooks locally to - create materials and push them to a git repository. You should just use - git directly, since the assumptions and design of nbgitpuller **will** - surprise you in unexpected ways if you are pushing with git but pulling - with nbgitpuller. -#. Your students are performing manual git operations on the git repository - cloned as well as using nbgitpuller. Mixing manual git operations + - automatic nbgitpuller operations is going to cause surprises on an ongoing - basis, and should be avoided. - -Installation -============ - -If you already have a JupyterHub, you can follow :ref:`these installation -instructions ` to install nbgitpuller there. They should also -work for installation on a local Jupyter Notebook installation without -JupyterHub. - -If you do *not* have a JupyterHub, we recommend trying out `The Littlest -JupyterHub `_ to set one up. It comes built -in with nbgitpuller. - -Using nbgitpuller as an instructor -================================== - -Once installed, you create a specially crafted web link (called -*nbgitpuller links*) and send to your students via any method you like - -course website, LMS, email, etc. This link will contain at least the -following information: - -#. The location of the JupyterHub you are sending them to. -#. The git repository where you have published your content. -#. Optionally, a particular file or directory you want to automatically - open for your students once the repository has been synchronized. Note the entire repository will be copied, not just the specified file. - -The first time a particular student clicks the link, a local copy of the -repository is made for the student. On successive clicks, the latest version -of the remote repository is fetched, and merged automatically with the -student's local copy using a :ref:`series of rules ` -that ensure students never get merge conflicts. - -You can generate such *nbgitpuller links* with the `generator -`_. - -There is also a video showing you how to use nbgitpuller - -.. raw:: html - - - -If you are interested in the details of available options when creating -the link, we have a :ref:`list of options ` as well. - -Full Contents -============= - -.. toctree:: - :maxdepth: 2 - - install - contributing - topic/automatic-merging - topic/url-options - topic/repo-best-practices - link diff --git a/docs/install.rst b/docs/install.rst index 98f42f08..57d5c17d 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -4,13 +4,34 @@ Installation ============ -You can install ``nbgitpuller`` from PyPI with ``pip`` in the same -environment where your jupyter notebook package is installed. +nbgitpuller can work on any computer, but it is most-commonly used with a JupyterHub. +By installing nbgitpuller in the user environment for your hub, it means that +all users will be able to click nbgitpuller links to get the content. + +.. admonition:: To set up a JupyterHub + :class: tip + + If you do *not* have a JupyterHub, we recommend trying out `The Littlest + JupyterHub `_ to set one up. + It comes built in with nbgitpuller. + + For more information about JupyterHub, see + `the JupyterHub Documentation `_. + +You can install ``nbgitpuller`` from PyPI with ``pip``: .. code:: bash pip install nbgitpuller +.. note:: + + If you use multiple environments in your JupyterHub, make sure you install + nbgitpuller in the environment that the jupyter notebook or + jupyter server process is running from. You can validate this by running + `jupyter serverextension list` - it should have an entry that says `nbgitpuller enabled`. + + Troubleshooting =============== diff --git a/docs/link.rst b/docs/link.rst index a39395d3..c7516897 100644 --- a/docs/link.rst +++ b/docs/link.rst @@ -3,6 +3,13 @@ nbgitpuller link generator Use the following form to create your own ``nbgitpuller`` links. +.. note:: + + Consider using the `nbgitpuller link generator browser extension `_ + instead! Available for `Firefox `_ and + `Chrome `_. + + .. raw:: html
@@ -131,6 +138,12 @@ Use the following form to create your own ``nbgitpuller`` links. Classic Jupyter Notebook
+
+ + +