adding documentation

.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

.gitignore

@@ -13,3 +13,6 @@ data8assets/
 .autopull_list
 summer/
 test-repo/
+
+.ipynb_checkpoints
+docs/_build

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.

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)

docs/link.js → 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 <input> 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);
         }
     )

docs/_templates/layout.html

@@ -0,0 +1,21 @@
+{%- extends "alabaster_jupyterhub/layout.html" %}
+
+<!-- Adding CSS to make the link generator wider -->
+{% block extrahead %}
+{% if pagename == 'link' %}
+<style>
+    div.body {
+        max-width: 1000px !important;
+        padding-right: 0px !important;
+    }
+</style>
+{% endif %}
+{{ super() }}
+{% endblock %}
+
+<!-- Don't include the "on this page" sidebar for the link generator -->
+{% block sidebar1 %}
+{% if pagename != 'link' %}
+{%- include "rightsidebar.html" %}
+{% endif %}
+{% endblock %}

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",
+    )
+]