Document how to do local development

docs/conf.py

@@ -3,21 +3,11 @@
 
 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_javascript("link_gen/link.js")
 
@@ -31,7 +21,10 @@ def setup(app):
 # 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"]
+extensions = [
+    "myst_parser",
+    "sphinx.ext.intersphinx",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -41,10 +34,6 @@ def setup(app):
 
 source_suffix = [".rst", ".md"]
 
-from recommonmark.parser import CommonMarkParser
-
-source_parsers = {".md": CommonMarkParser}
-
 
 # The master toctree document.
 master_doc = "index"

docs/contributing.md

@@ -0,0 +1,45 @@
+# Contributing
+
+## Setup
+
+nbgitpuller is a [jupyter
+serverextension](https://jupyter-notebook.readthedocs.io/en/stable/extending/handlers.html),
+and hence can be developed locally without needing a JupyterHub.
+
+1. Fork the nbgitpuller repository and `git clone` it to your local computer.
+
+2. Inside the nbgitpuller clone on your local machine, setup a virtual
+   environment to do development in
+
+   ```bash
+   python3 -m venv venv
+   source venv/bin/activate
+   ```
+
+3. Install nbgitpuller with its dependencies in this virtual environment
+
+   ```bash
+   pip install -e .
+   ```
+
+4. Enable the nbgitpuller jupyter serverextension
+
+   ```bash
+   jupyter serverextension enable --sys-prefix nbgitpuller
+   ```
+
+5. Start the notebook server. This will open the classic notebook in your web
+   browser, and automatically authenticate you as a side effect.
+
+   ```bash
+   jupyter notebook
+   ```
+
+6. You can now test nbgitpuller locally, by hitting the `/git-pull` url with any
+   of the [URL query parameters](topic/url-options.rst). For example, to pull the
+   [data-8/textbook](https://github.com/data-8/textbook) repository's `gh-pages`
+   branch, you can use the following URL:
+
+   ```
+   http://localhost:8888/git-sync?repo=https://github.com/data-8/textbook&branch=gh-pages
+   ```

docs/doc-requirements.txt

@@ -1,9 +1,3 @@
-recommonmark==0.4.0
+myst_parser
 sphinx_copybutton
-traitlets
-jupyterhub
-sphinx>=1.3.6,!=1.5.4
 sphinx-book-theme
-memory_profiler
-pytest
-PyGitHub

docs/index.rst

@@ -89,6 +89,7 @@ Full Contents
    :maxdepth: 2
 
    install
+   contributing
    topic/automatic-merging
    topic/url-options
    link