diff --git a/.circleci/config.yml b/.circleci/config.yml new file mode 100644 index 00000000..7059aeb0 --- /dev/null +++ b/.circleci/config.yml @@ -0,0 +1,38 @@ +version: 2 +jobs: + build_docs: + docker: + - image: circleci/python:3.6-stretch + 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 + + - store_artifacts: + path: docs/_build/html/ + destination: html + + +workflows: + version: 2 + default: + jobs: + - build_docs \ No newline at end of file diff --git a/.gitignore b/.gitignore index a64ee243..7626168a 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,6 @@ data8assets/ .autopull_list summer/ test-repo/ + +.ipynb_checkpoints +docs/_build \ No newline at end of file diff --git a/README.md b/README.md index 193fa7ee..4f7ec9e3 100644 --- a/README.md +++ b/README.md @@ -3,11 +3,10 @@ Create links for one-way synchronization of a remote git repository to a local git repository, with automatic conflict resolution. Meant for use with a Jupyter server. -[Generate your own nbgitpuller links here](https://jupyterhub.github.io/nbgitpuller/link). +* [**For more information, check out the nbgitpuller documentation**](https://jupyterhub.github.io/nbgitpuller) +* [Generate your own nbgitpuller links here](https://jupyterhub.github.io/nbgitpuller/link.html). -[YouTube video instructions for teachers.](https://youtu.be/o7U0ZuICVFg) - -![nbgitpuller demo](docs/nbpuller.gif) +![nbgitpuller demo](docs/_static/nbpuller.gif) # Installation @@ -27,54 +26,6 @@ into the user's current folder within Jupyter, while rendering a nice status pag This is especially useful when running on a JupyterHub, since it allows easy distribution of materials to users without requiring them to understand git. -# Merging behavior - -When a link is clicked, we try to make opinionated intelligent guesses on how to -do a merge automatically, without making the user do a conflict resolution. -nbgitpuller is designed to be used by folks who do not know that git is being used -underneath, and are only pulling content one way from a source and modifying it - -not pushing it back. -So we have made the following opinionated decisions. - - -1. If content has changed in both places, prefer local changes over remote changes. -2. If a file was deleted locally but present in the remote, remote file is restored - to local repository. This allows users to get a 'fresh copy' of a file by - just deleting the file locally & clicking the link again. -3. If a file exists locally but is untracked by git (maybe someone uploaded it manually), - then rename the file, and pull in remote copy. - -# When to use nbgitpuller - -You should use this when: - -1. 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. -2. 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 this when: - -1. 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. -2. 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. - -# How to use nbgitpuller - -1. Visit the nbgitpuller link generator at https://jupyterhub.github.io/nbgitpuller/link. -2. Enter the IP address or URL to your JupyterHub. Include http:// or https:// as appropriate. -3. Enter an alternative URL path if desired. If not set, the generated link will take users to the default hub url, however this can be changed. For example specifying "lab" will launch JupyterLab if installed. Entering "path/to/a/notebook.ipynb" will open that notebook. -4. Enter the URL to your Git repository. This can reference any Git service provider such as GitHub, GitLab, or a local instance. -5. If your git repository is using a non-default branch name, you can specify that under branch. Most people do not need to customize this. - -The link printed at the bottom of the form can be distributed to users. You can also click it to test that it is working as intended, and adjust the form values until you get something you are happy with. - -To preseed the form, append query string arguments to the link generator itself, for example https://jupyterhub.github.io/nbgitpuller/link?hub=http://jupyterhub.example.com. This may be useful when you want to suggest initial values to someone else. The other parameters are `urlpath`, `repo`, and `branch`. Resetting the form will remove the seeded values and re-enable the form fields. - # Local development You can easily set up to develop this locally, without requiring a JupyterHub. It requires python3. @@ -109,17 +60,3 @@ You can easily set up to develop this locally, without requiring a JupyterHub. I localhost:8888/git-pull?repo=https://github.com/data-8/materials-fa17 ``` 7. Make the changes you want to make, and restart the jupyter notebook for them to take effect. - -# Using the command line interface - -It is also possible to use `nbgitpuller` from the command line. For example, -here's how to synchronize the repository listed above using the command line: - -``` -gitpuller https://github.com/data-8/materials-fa17 master my_materials_fa17 -``` - -This will synchronize the `master` branch of the repository to a folder -called `my_materials_fa17`. - -See the command line help for more information. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..9764015b --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = Binder +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.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). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/link.js b/docs/_static/link_gen/link.js similarity index 97% rename from docs/link.js rename to docs/_static/link_gen/link.js index 4655d3b8..874962fb 100644 --- a/docs/link.js +++ b/docs/_static/link_gen/link.js @@ -3,10 +3,10 @@ function generateRegularUrl(hubUrl, urlPath, repoUrl, branch) { // assume hubUrl is a valid URL var url = new URL(hubUrl); - + url.searchParams.set('repo', repoUrl); - if (urlPath) { + if (urlPath) { url.searchParams.set('urlpath', urlPath); } @@ -89,7 +89,7 @@ function populateFromQueryString() { var params = new URLSearchParams(window.location.search); // Parameters are read from query string, and fields are set to them var allowedParams = ['hub', 'repo', 'branch']; - for (var i=0; i < allowedParams.length; i++) { + for (var i = 0; i < allowedParams.length; i++) { var param = allowedParams[i]; if (params.has(param)) { document.getElementById(param).value = params.get(param); @@ -132,12 +132,12 @@ function render() { function main() { // Hook up any changes in form elements to call render() document.querySelectorAll('#linkgenerator input[type="radio"]').forEach( - function(element) { + function (element) { element.addEventListener('change', render); } ) document.querySelectorAll('#linkgenerator input[type="text"], #linkgenerator input[type="url"]').forEach( - function(element) { + function (element) { element.addEventListener('input', render); } ) diff --git a/docs/vendor/bootstrap-4.1.3/css/bootstrap-grid.css b/docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap-grid.css similarity index 100% rename from docs/vendor/bootstrap-4.1.3/css/bootstrap-grid.css rename to docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap-grid.css diff --git a/docs/vendor/bootstrap-4.1.3/css/bootstrap-grid.css.map b/docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap-grid.css.map similarity index 100% rename from docs/vendor/bootstrap-4.1.3/css/bootstrap-grid.css.map rename to docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap-grid.css.map diff --git a/docs/vendor/bootstrap-4.1.3/css/bootstrap-grid.min.css b/docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap-grid.min.css similarity index 100% rename from docs/vendor/bootstrap-4.1.3/css/bootstrap-grid.min.css rename to docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap-grid.min.css diff --git a/docs/vendor/bootstrap-4.1.3/css/bootstrap-grid.min.css.map b/docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap-grid.min.css.map similarity index 100% rename from docs/vendor/bootstrap-4.1.3/css/bootstrap-grid.min.css.map rename to docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap-grid.min.css.map diff --git a/docs/vendor/bootstrap-4.1.3/css/bootstrap-reboot.css b/docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap-reboot.css similarity index 100% rename from docs/vendor/bootstrap-4.1.3/css/bootstrap-reboot.css rename to docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap-reboot.css diff --git a/docs/vendor/bootstrap-4.1.3/css/bootstrap-reboot.css.map b/docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap-reboot.css.map similarity index 100% rename from docs/vendor/bootstrap-4.1.3/css/bootstrap-reboot.css.map rename to docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap-reboot.css.map diff --git a/docs/vendor/bootstrap-4.1.3/css/bootstrap-reboot.min.css b/docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap-reboot.min.css similarity index 100% rename from docs/vendor/bootstrap-4.1.3/css/bootstrap-reboot.min.css rename to docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap-reboot.min.css diff --git a/docs/vendor/bootstrap-4.1.3/css/bootstrap-reboot.min.css.map b/docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap-reboot.min.css.map similarity index 100% rename from docs/vendor/bootstrap-4.1.3/css/bootstrap-reboot.min.css.map rename to docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap-reboot.min.css.map diff --git a/docs/vendor/bootstrap-4.1.3/css/bootstrap.css b/docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap.css similarity index 100% rename from docs/vendor/bootstrap-4.1.3/css/bootstrap.css rename to docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap.css diff --git a/docs/vendor/bootstrap-4.1.3/css/bootstrap.css.map b/docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap.css.map similarity index 100% rename from docs/vendor/bootstrap-4.1.3/css/bootstrap.css.map rename to docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap.css.map diff --git a/docs/vendor/bootstrap-4.1.3/css/bootstrap.min.css b/docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap.min.css similarity index 100% rename from docs/vendor/bootstrap-4.1.3/css/bootstrap.min.css rename to docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap.min.css diff --git a/docs/vendor/bootstrap-4.1.3/css/bootstrap.min.css.map b/docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap.min.css.map similarity index 100% rename from docs/vendor/bootstrap-4.1.3/css/bootstrap.min.css.map rename to docs/_static/link_gen/vendor/bootstrap-4.1.3/css/bootstrap.min.css.map diff --git a/docs/vendor/bootstrap-4.1.3/js/bootstrap.bundle.js b/docs/_static/link_gen/vendor/bootstrap-4.1.3/js/bootstrap.bundle.js similarity index 100% rename from docs/vendor/bootstrap-4.1.3/js/bootstrap.bundle.js rename to docs/_static/link_gen/vendor/bootstrap-4.1.3/js/bootstrap.bundle.js diff --git a/docs/vendor/bootstrap-4.1.3/js/bootstrap.bundle.js.map b/docs/_static/link_gen/vendor/bootstrap-4.1.3/js/bootstrap.bundle.js.map similarity index 100% rename from docs/vendor/bootstrap-4.1.3/js/bootstrap.bundle.js.map rename to docs/_static/link_gen/vendor/bootstrap-4.1.3/js/bootstrap.bundle.js.map diff --git a/docs/vendor/bootstrap-4.1.3/js/bootstrap.bundle.min.js b/docs/_static/link_gen/vendor/bootstrap-4.1.3/js/bootstrap.bundle.min.js similarity index 100% rename from docs/vendor/bootstrap-4.1.3/js/bootstrap.bundle.min.js rename to docs/_static/link_gen/vendor/bootstrap-4.1.3/js/bootstrap.bundle.min.js diff --git a/docs/vendor/bootstrap-4.1.3/js/bootstrap.bundle.min.js.map b/docs/_static/link_gen/vendor/bootstrap-4.1.3/js/bootstrap.bundle.min.js.map similarity index 100% rename from docs/vendor/bootstrap-4.1.3/js/bootstrap.bundle.min.js.map rename to docs/_static/link_gen/vendor/bootstrap-4.1.3/js/bootstrap.bundle.min.js.map diff --git a/docs/vendor/bootstrap-4.1.3/js/bootstrap.js b/docs/_static/link_gen/vendor/bootstrap-4.1.3/js/bootstrap.js similarity index 100% rename from docs/vendor/bootstrap-4.1.3/js/bootstrap.js rename to docs/_static/link_gen/vendor/bootstrap-4.1.3/js/bootstrap.js diff --git a/docs/vendor/bootstrap-4.1.3/js/bootstrap.js.map b/docs/_static/link_gen/vendor/bootstrap-4.1.3/js/bootstrap.js.map similarity index 100% rename from docs/vendor/bootstrap-4.1.3/js/bootstrap.js.map rename to docs/_static/link_gen/vendor/bootstrap-4.1.3/js/bootstrap.js.map diff --git a/docs/vendor/bootstrap-4.1.3/js/bootstrap.min.js b/docs/_static/link_gen/vendor/bootstrap-4.1.3/js/bootstrap.min.js similarity index 100% rename from docs/vendor/bootstrap-4.1.3/js/bootstrap.min.js rename to docs/_static/link_gen/vendor/bootstrap-4.1.3/js/bootstrap.min.js diff --git a/docs/vendor/bootstrap-4.1.3/js/bootstrap.min.js.map b/docs/_static/link_gen/vendor/bootstrap-4.1.3/js/bootstrap.min.js.map similarity index 100% rename from docs/vendor/bootstrap-4.1.3/js/bootstrap.min.js.map rename to docs/_static/link_gen/vendor/bootstrap-4.1.3/js/bootstrap.min.js.map diff --git a/docs/vendor/jquery-3.3.1.slim.min.js b/docs/_static/link_gen/vendor/jquery-3.3.1.slim.min.js similarity index 100% rename from docs/vendor/jquery-3.3.1.slim.min.js rename to docs/_static/link_gen/vendor/jquery-3.3.1.slim.min.js diff --git a/docs/nbpuller.gif b/docs/_static/nbpuller.gif similarity index 100% rename from docs/nbpuller.gif rename to docs/_static/nbpuller.gif diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html new file mode 100644 index 00000000..a1f824ad --- /dev/null +++ b/docs/_templates/layout.html @@ -0,0 +1,21 @@ +{%- extends "alabaster_jupyterhub/layout.html" %} + + +{% block extrahead %} +{% if pagename == 'link' %} + +{% endif %} +{{ super() }} +{% endblock %} + + +{% block sidebar1 %} +{% if pagename != 'link' %} +{%- include "rightsidebar.html" %} +{% endif %} +{% endblock %} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..881c44f8 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,178 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- + +import os +import requests +from recommonmark.transform import AutoStructify + +github_doc_root = "https://github.com/rtfd/recommonmark/tree/master/doc/" + + +def setup(app): + app.add_config_value( + "recommonmark_config", + { + "url_resolver": lambda url: github_doc_root + url, + "auto_toc_tree_section": "Contents", + }, + True, + ) + app.add_transform(AutoStructify) + app.add_stylesheet("custom.css") + app.add_stylesheet("link_gen/vendor/bootstrap-4.1.3/css/bootstrap.min.css") + app.add_javascript("link_gen/vendor/jquery-3.3.1.slim.min.js") + app.add_javascript("link_gen/link.js") + app.add_javascript("link_gen/vendor/bootstrap-4.1.3/js/bootstrap.bundle.min.js") + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ["sphinx_copybutton"] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: + +source_suffix = [".rst", ".md"] + +from recommonmark.parser import CommonMarkParser + +source_parsers = {".md": CommonMarkParser} + + +# The master toctree document. +master_doc = "index" + +# General information about the project. +project = "nbgitpuller" +copyright = "2017, The nbgitpuller Team" +author = "The nbgitpuller Team" + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = "0.1b" +# The full version, including alpha/beta/rc tags. +release = "0.1b" + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# 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" + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +import alabaster_jupyterhub + +html_theme = "alabaster_jupyterhub" +html_theme_path = [alabaster_jupyterhub.get_html_theme_path()] + +# 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 +# documentation. +# +# html_theme_options = {} + +html_context = { + "github_user": "jupyterhub", + "github_repo": "nbgitpuller", + "github_version": "master", + "doc_path": "doc", + "source_suffix": source_suffix, +} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = "nbgitpullerdoc" + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ( + master_doc, + "nbgitpuller.tex", + "nbgitpuller Documentation", + "The nbgitpuller Team", + "manual", + ) +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [(master_doc, "nbgitpuller", "nbgitpuller Documentation", [author], 1)] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ( + master_doc, + "nbgitpuller", + "nbgitpuller Documentation", + author, + "nbgitpuller", + "One line description of project.", + "Miscellaneous", + ) +] diff --git a/docs/doc-requirements.txt b/docs/doc-requirements.txt new file mode 100644 index 00000000..489ed3f7 --- /dev/null +++ b/docs/doc-requirements.txt @@ -0,0 +1,10 @@ +recommonmark==0.4.0 +sphinx_copybutton +traitlets +jupyterhub +sphinx>=1.3.6,!=1.5.4 +alabaster +alabaster_jupyterhub +memory_profiler +pytest +PyGitHub \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..2a6477fe --- /dev/null +++ b/docs/index.md @@ -0,0 +1,49 @@ +# NBGitpuller + +Create links for one-way synchronization of a remote git repository to a local git repository, +with automatic conflict resolution. Meant for use with a Jupyter server. + +![nbgitpuller demo](_static/nbpuller.gif) + +## Contents + +See below for some helpful links on how to use `nbgitpuller`. + +* [Using nbgitpuller](using.md) +* [Generate your own nbgitpuller links here](link.rst) +* [YouTube video instructions for teachers.](https://youtu.be/o7U0ZuICVFg) + +## Installation + +You can install nbgitpuller from PyPI. + + pip install nbgitpuller + +You can then enable the serverextension + + jupyter serverextension enable --py nbgitpuller --sys-prefix + +## What is it? + +nbgitpuller allows you to construct a URL that points to a remote git repository. +When it is clicked, nbgitpuller will pull the contents of this repository +into the user's current folder within Jupyter, while rendering a nice status page. +This is especially useful when running on a JupyterHub, since it allows easy distribution +of materials to users without requiring them to understand git. + +## Merging behavior + +When a link is clicked, we try to make opinionated intelligent guesses on how to +do a merge automatically, without making the user do a conflict resolution. +nbgitpuller is designed to be used by folks who do not know that git is being used +underneath, and are only pulling content one way from a source and modifying it - +not pushing it back. +So we have made the following opinionated decisions. + + +1. If content has changed in both places, prefer local changes over remote changes. +2. If a file was deleted locally but present in the remote, remote file is restored + to local repository. This allows users to get a 'fresh copy' of a file by + just deleting the file locally & clicking the link again. +3. If a file exists locally but is untracked by git (maybe someone uploaded it manually), + then rename the file, and pull in remote copy. \ No newline at end of file diff --git a/docs/link.html b/docs/link.html deleted file mode 100644 index d7b33aa9..00000000 --- a/docs/link.html +++ /dev/null @@ -1,136 +0,0 @@ - - - - - - - - - - - nbgitpuller Link Generator - - -
-

nbgitpuller link generator

- -
- -
- - - -
-
- -
-
- -
-
- -
- -
- -
- -
- Must be a valid web URL -
- - The JupyterHub to send users to. - nbgitpuller must be installed in this hub. - -
-
- -
- -
- -
- Must be a valid git URL -
-
-
-
-
- branch -
- -
-
-
- -
- -
- - - This file or directory from within the repo will open when user clicks the link. - -
-
- -
-
- - - -
-
-
- - -
-
- - -
-
- - -
-
- - - -
-
-
- -
-
- - diff --git a/docs/link.rst b/docs/link.rst new file mode 100644 index 00000000..e4b3026a --- /dev/null +++ b/docs/link.rst @@ -0,0 +1,134 @@ +nbgitpuller link generator +========================== + +Use the following form to create your own ``nbgitpuller`` links. + +.. raw:: html + +
+
+ +
+ + + +
+
+ +
+
+ +
+
+ +
+ +
+ +
+ +
+ Must be a valid web URL +
+ + The JupyterHub to send users to. + nbgitpuller must be installed in this hub. + +
+
+ +
+ +
+ +
+ Must be a valid git URL +
+
+
+
+
+ branch +
+ +
+
+
+ +
+ +
+ + + This file or directory from within the repo will open when user clicks the link. + +
+
+ +
+
+ + + +
+
+
+ + +
+
+ + +
+
+ + +
+
+ + + +
+
+
+ +
+
+


+ + +**Pre-populating some fields in the link generator** + +You can pre-populate some fields in order to make it easier for some +users to create their own links. To do so, use the following URL +parameters **when accessing this page**: + +* ``hub`` is the URL of a JupyterHub +* ``repo`` is the URL of a github repository to which you're linking +* ``branch`` is the branch you wish to pull from the Repository + +For example, the following URL will pre-populate the form with the +UC Berkeley DataHub as the JupyterHub:: + + https://jupyterhub.github.io/nbgitpuller/link?hub=https://datahub.berkeley.edu \ No newline at end of file diff --git a/docs/using.md b/docs/using.md new file mode 100644 index 00000000..dae67152 --- /dev/null +++ b/docs/using.md @@ -0,0 +1,49 @@ +# Using nbgitpuller + +This page covers some of the common reasons and ways to use nbgitpuller. + +## When to use nbgitpuller + +You should use nbgitpuller when: + +1. 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. +2. 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 this when: + +1. 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. +2. 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. + +## How to use nbgitpuller + +1. Visit the nbgitpuller link generator at https://jupyterhub.github.io/nbgitpuller/link.html. +2. Enter the IP address or URL to your JupyterHub. Include http:// or https:// as appropriate. +3. Enter an alternative URL path if desired. If not set, the generated link will take users to the default hub url, however this can be changed. For example specifying "lab" will launch JupyterLab if installed. Entering "path/to/a/notebook.ipynb" will open that notebook. +4. Enter the URL to your Git repository. This can reference any Git service provider such as GitHub, GitLab, or a local instance. +5. If your git repository is using a non-default branch name, you can specify that under branch. Most people do not need to customize this. + +The link printed at the bottom of the form can be distributed to users. You can also click it to test that it is working as intended, and adjust the form values until you get something you are happy with. + +To preseed the form, append query string arguments to the link generator itself, for example https://jupyterhub.github.io/nbgitpuller/link?hub=http://jupyterhub.example.com. This may be useful when you want to suggest initial values to someone else. The other parameters are `urlpath`, `repo`, and `branch`. Resetting the form will remove the seeded values and re-enable the form fields. + + +## Using the command line interface + +It is also possible to use `nbgitpuller` from the command line. For example, +here's how to synchronize the repository listed above using the command line: + +``` +gitpuller https://github.com/data-8/materials-fa17 master my_materials_fa17 +``` + +This will synchronize the `master` branch of the repository to a folder +called `my_materials_fa17`. + +See the command line help for more information.