Skip to content

Commit 734641a

Browse files
sean-morrissean-morris
committed
fixed conflicts
2 parents eefdbfd + ddb0958 commit 734641a

16 files changed

+403
-76
lines changed

‎.buildinfo‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
# Sphinx build info version 1
22
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
3-
config: 48b8daa921fa878b7d67db3fbd07c575
3+
config: 2bad9913f280836a9e98d9943c494766
44
tags: 645f666f9bcd5a90fca523b33c5a78b7

‎_sources/contributing.md.txt‎

Lines changed: 99 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,10 @@
22

33
## Setup
44

5-
nbgitpuller is a [jupyter
6-
serverextension](https://jupyter-notebook.readthedocs.io/en/stable/extending/handlers.html),
7-
and hence can be developed locally without needing a JupyterHub.
5+
nbgitpuller is a jupyter extension that works with both the
6+
[classic Notebook Server](https://jupyter-notebook.readthedocs.io/en/stable/extending/handlers.html),
7+
and the newer [Jupyter Server](https://jupyter-server.readthedocs.io/en/latest/operators/configuring-extensions.html).
8+
Hence, nbgitpuller can be developed locally without needing a JupyterHub.
89

910
1. Fork the nbgitpuller repository and `git clone` it to your local computer.
1011

@@ -16,30 +17,117 @@ and hence can be developed locally without needing a JupyterHub.
1617
source venv/bin/activate
1718
```
1819

19-
3. Install nbgitpuller with its dependencies in this virtual environment
20+
3. Install development time dependencies in this virtual environment
21+
22+
```bash
23+
pip install -r dev-requirements.txt
24+
```
25+
26+
4. Install nbgitpuller with its dependencies in this virtual environment
2027

2128
```bash
2229
pip install -e .
2330
```
2431

25-
4. Enable the nbgitpuller jupyter serverextension
32+
5. Install the NodeJS dependencies from package.json.
2633

2734
```bash
28-
jupyter serverextension enable --sys-prefix nbgitpuller
35+
npm install
2936
```
3037

31-
5. Start the notebook server. This will open the classic notebook in your web
32-
browser, and automatically authenticate you as a side effect.
38+
6. Create the JS and CSS bundles.
3339

3440
```bash
35-
jupyter notebook
41+
npm run webpack
3642
```
3743

38-
6. You can now test nbgitpuller locally, by hitting the `/git-pull` url with any
44+
7. Enable the nbgitpuller extension:
45+
* as a jupyter serverextension (classic Notebook Server extension)
46+
47+
```bash
48+
jupyter serverextension enable --sys-prefix nbgitpuller
49+
```
50+
* as a jupyter server extension
51+
```bash
52+
jupyter server extension enable --sys-prefix nbgitpuller
53+
```
54+
55+
8. Start the notebook server:
56+
57+
* You can either start the classical Notebook server.
58+
This will open the classic notebook in your web
59+
browser, and automatically authenticate you as a side effect.
60+
61+
```bash
62+
jupyter notebook
63+
```
64+
65+
* Or you can start the new Jupyter Server.
66+
```bash
67+
jupyter server
68+
```
69+
This won't open any notebook interface, unless you don't enable one
70+
([`nbclassic`](https://github.com/jupyterlab/nbclassic) or [`jupyterlab`](https://github.com/jupyterlab/jupyterlab))
71+
as a jupyter server extension.
72+
```bash
73+
jupyter server extension enable --sys-prefix nbclassic
74+
```
75+
or
76+
```bash
77+
jupyter server extension enable --sys-prefix jupyterlab
78+
```
79+
80+
9. You can now test nbgitpuller locally, by hitting the `/git-pull` url with any
3981
of the [URL query parameters](topic/url-options.rst). For example, to pull the
4082
[data-8/textbook](https://github.com/data-8/textbook) repository's `gh-pages`
4183
branch, you can use the following URL:
4284

4385
```
44-
http://localhost:8888/git-sync?repo=https://github.com/data-8/textbook&branch=gh-pages
86+
http://localhost:8888/git-pull?repo=https://github.com/data-8/textbook&branch=gh-pages
4587
```
88+
89+
10. If you make changes to nbgitpuller's python code, you need to restart the `jupyter notebook`
90+
process (started in step 5) to see your changes take effect. This is not needed if
91+
you are only working on the javascript or css.
92+
93+
## Running the flake8 linter
94+
95+
[flake8](https://flake8.pycqa.org/en/latest/) is used to validate python coding style. The
96+
flake8 config is in `.flake8`, and is not super strict. You should be able to run
97+
`flake8` in the root directory of the repository to get a list of issues to be fixed.
98+
99+
## Running tests
100+
101+
[pytest](https://docs.pytest.org/) is used to run unit and integration tests,
102+
under the `tests/` directory. If you add new functionality, you should also add
103+
tests to cover it. You can run the tests locally with `py.test tests/`
104+
105+
## Building documentation
106+
107+
[sphinx](https://www.sphinx-doc.org/) is used to write and maintain documentation, under
108+
the `docs/` directory. If you add any new functionality, you should write documentaiton
109+
for it as well. A mix of [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)
110+
and [MyST Markdown](https://myst-parser.readthedocs.io) is used to write our documentation,
111+
although we would like to migrate purely to MyST markdown in the future.
112+
113+
1. Install the packages needed to build the documentation
114+
115+
```bash
116+
pip install -r docs/doc-requirements.txt
117+
```
118+
119+
2. Build the documentation by using `make` inside the `docs` folder. This will
120+
internally call `sphinx`
121+
122+
```bash
123+
cd docs
124+
make html
125+
```
126+
127+
3. Preview the documentation by opening `_build/html/index.html` file in
128+
your browser. From inside the `docs` folder, you can run either
129+
`open _build/html/index.html` (on MacOS) or `xdg-open _build/html/index.html`
130+
to quickly open the file in the browser.
131+
132+
4. You can run `make html` again after making further changes to see their
133+
effects.

‎_static/__pycache__/__init__.cpython-36.pyc‎

0 Bytes
Binary file not shown.

‎_static/link_gen/link.js‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -130,11 +130,6 @@ function changeTab(div) {
130130
var hub_help_text = document.getElementById("hub-help-text");
131131
var env_repo_group = document.getElementById("env-repo-group");
132132
var env_repo = document.getElementById("env-repo");
133-
<<<<<<< HEAD
134-
=======
135-
// var env_repo_branch = document.getElementById("env-branch");
136-
// var env_repo_help_text = document.getElementById("env-repo-help-text");
137-
>>>>>>> b5b1e8e... JupyterHub link gen working
138133
var id = div.id;
139134
var form = document.getElementById('linkgenerator');
140135

‎_static/sphinx-book-theme.acff12b8f9c144ce68a297486a2fa670.css‎

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎_static/sphinx-book-theme.e8f53015daec13862f6db5e763c41738.css‎

Lines changed: 5 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎contributing.html‎

Lines changed: 139 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323

2424

2525
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
26-
<link rel="stylesheet" href="_static/sphinx-book-theme.acff12b8f9c144ce68a297486a2fa670.css" type="text/css" />
26+
<link rel="stylesheet" href="_static/sphinx-book-theme.e8f53015daec13862f6db5e763c41738.css" type="text/css" />
2727
<link rel="stylesheet" type="text/css" href="_static/custom.css" />
2828

2929
<link rel="preload" as="script" href="_static/js/index.1c5a1a01449ed65a7b51.js">
@@ -62,6 +62,9 @@ <h3><a href="index.html">Table of Contents</a></h3>
6262
<li class="toctree-l1"><a class="reference internal" href="install.html">Installation</a></li>
6363
<li class="toctree-l1 current"><a class="current reference internal" href="#">Contributing</a><ul>
6464
<li class="toctree-l2"><a class="reference internal" href="#setup">Setup</a></li>
65+
<li class="toctree-l2"><a class="reference internal" href="#running-the-flake8-linter">Running the flake8 linter</a></li>
66+
<li class="toctree-l2"><a class="reference internal" href="#running-tests">Running tests</a></li>
67+
<li class="toctree-l2"><a class="reference internal" href="#building-documentation">Building documentation</a></li>
6568
</ul>
6669
</li>
6770
<li class="toctree-l1"><a class="reference internal" href="topic/automatic-merging.html">Automatic Merging Behavior</a></li>
@@ -162,13 +165,28 @@ <h3 id="searchlabel">Quick search</h3>
162165
<div class="tocsection onthispage pt-5 pb-3">
163166
<i class="fas fa-list"></i> Contents
164167
</div>
165-
<nav id="bd-toc-nav">
168+
<nav id="bd-toc-nav" aria-label="Page">
166169
<ul class="visible nav section-nav flex-column">
167170
<li class="toc-h2 nav-item toc-entry">
168171
<a class="reference internal nav-link" href="#setup">
169172
Setup
170173
</a>
171174
</li>
175+
<li class="toc-h2 nav-item toc-entry">
176+
<a class="reference internal nav-link" href="#running-the-flake8-linter">
177+
Running the flake8 linter
178+
</a>
179+
</li>
180+
<li class="toc-h2 nav-item toc-entry">
181+
<a class="reference internal nav-link" href="#running-tests">
182+
Running tests
183+
</a>
184+
</li>
185+
<li class="toc-h2 nav-item toc-entry">
186+
<a class="reference internal nav-link" href="#building-documentation">
187+
Building documentation
188+
</a>
189+
</li>
172190
</ul>
173191

174192
</nav>
@@ -180,13 +198,14 @@ <h3 id="searchlabel">Quick search</h3>
180198

181199
<div>
182200

183-
<div class="section" id="contributing">
201+
<div class="tex2jax_ignore mathjax_ignore section" id="contributing">
184202
<h1>Contributing<a class="headerlink" href="#contributing" title="Permalink to this headline"></a></h1>
185203
<div class="section" id="setup">
186204
<h2>Setup<a class="headerlink" href="#setup" title="Permalink to this headline"></a></h2>
187-
<p>nbgitpuller is a <a class="reference external" href="https://jupyter-notebook.readthedocs.io/en/stable/extending/handlers.html">jupyter
188-
serverextension</a>,
189-
and hence can be developed locally without needing a JupyterHub.</p>
205+
<p>nbgitpuller is a jupyter extension that works with both the
206+
<a class="reference external" href="https://jupyter-notebook.readthedocs.io/en/stable/extending/handlers.html">classic Notebook Server</a>,
207+
and the newer <a class="reference external" href="https://jupyter-server.readthedocs.io/en/latest/operators/configuring-extensions.html">Jupyter Server</a>.
208+
Hence, nbgitpuller can be developed locally without needing a JupyterHub.</p>
190209
<ol>
191210
<li><p>Fork the nbgitpuller repository and <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span></code> it to your local computer.</p></li>
192211
<li><p>Inside the nbgitpuller clone on your local machine, setup a virtual
@@ -196,30 +215,117 @@ <h2>Setup<a class="headerlink" href="#setup" title="Permalink to this headline">
196215
</pre></div>
197216
</div>
198217
</li>
218+
<li><p>Install development time dependencies in this virtual environment</p>
219+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pip install -r dev-requirements.txt
220+
</pre></div>
221+
</div>
222+
</li>
199223
<li><p>Install nbgitpuller with its dependencies in this virtual environment</p>
200224
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pip install -e .
201225
</pre></div>
202226
</div>
203227
</li>
204-
<li><p>Enable the nbgitpuller jupyter serverextension</p>
228+
<li><p>Install the NodeJS dependencies from package.json.</p>
229+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>npm install
230+
</pre></div>
231+
</div>
232+
</li>
233+
<li><p>Create the JS and CSS bundles.</p>
234+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>npm run webpack
235+
</pre></div>
236+
</div>
237+
</li>
238+
<li><p>Enable the nbgitpuller extension:</p>
239+
<ul>
240+
<li><p>as a jupyter serverextension (classic Notebook Server extension)</p>
205241
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>jupyter serverextension <span class="nb">enable</span> --sys-prefix nbgitpuller
206242
</pre></div>
207243
</div>
208244
</li>
209-
<li><p>Start the notebook server. This will open the classic notebook in your web
245+
<li><p>as a jupyter server extension</p>
246+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>jupyter server extension <span class="nb">enable</span> --sys-prefix nbgitpuller
247+
</pre></div>
248+
</div>
249+
</li>
250+
</ul>
251+
</li>
252+
<li><p>Start the notebook server:</p>
253+
<ul>
254+
<li><p>You can either start the classical Notebook server.
255+
This will open the classic notebook in your web
210256
browser, and automatically authenticate you as a side effect.</p>
211257
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>jupyter notebook
212258
</pre></div>
213259
</div>
214260
</li>
261+
<li><p>Or you can start the new Jupyter Server.</p>
262+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>jupyter server
263+
</pre></div>
264+
</div>
265+
<p>This won’t open any notebook interface, unless you don’t enable one
266+
(<a class="reference external" href="https://github.com/jupyterlab/nbclassic"><code class="docutils literal notranslate"><span class="pre">nbclassic</span></code></a> or <a class="reference external" href="https://github.com/jupyterlab/jupyterlab"><code class="docutils literal notranslate"><span class="pre">jupyterlab</span></code></a>)
267+
as a jupyter server extension.</p>
268+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>jupyter server extension <span class="nb">enable</span> --sys-prefix nbclassic
269+
</pre></div>
270+
</div>
271+
<p>or</p>
272+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>jupyter server extension <span class="nb">enable</span> --sys-prefix jupyterlab
273+
</pre></div>
274+
</div>
275+
</li>
276+
</ul>
277+
</li>
215278
<li><p>You can now test nbgitpuller locally, by hitting the <code class="docutils literal notranslate"><span class="pre">/git-pull</span></code> url with any
216279
of the <a class="reference internal" href="topic/url-options.html"><span class="doc std std-doc">URL query parameters</span></a>. For example, to pull the
217280
<a class="reference external" href="https://github.com/data-8/textbook">data-8/textbook</a> repository’s <code class="docutils literal notranslate"><span class="pre">gh-pages</span></code>
218281
branch, you can use the following URL:</p>
219-
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>http://localhost:8888/git-sync?repo=https://github.com/data-8/textbook&amp;branch=gh-pages
282+
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>http://localhost:8888/git-pull?repo=https://github.com/data-8/textbook&amp;branch=gh-pages
283+
</pre></div>
284+
</div>
285+
</li>
286+
<li><p>If you make changes to nbgitpuller’s python code, you need to restart the <code class="docutils literal notranslate"><span class="pre">jupyter</span> <span class="pre">notebook</span></code>
287+
process (started in step 5) to see your changes take effect. This is not needed if
288+
you are only working on the javascript or css.</p></li>
289+
</ol>
290+
</div>
291+
<div class="section" id="running-the-flake8-linter">
292+
<h2>Running the flake8 linter<a class="headerlink" href="#running-the-flake8-linter" title="Permalink to this headline"></a></h2>
293+
<p><a class="reference external" href="https://flake8.pycqa.org/en/latest/">flake8</a> is used to validate python coding style. The
294+
flake8 config is in <code class="docutils literal notranslate"><span class="pre">.flake8</span></code>, and is not super strict. You should be able to run
295+
<code class="docutils literal notranslate"><span class="pre">flake8</span></code> in the root directory of the repository to get a list of issues to be fixed.</p>
296+
</div>
297+
<div class="section" id="running-tests">
298+
<h2>Running tests<a class="headerlink" href="#running-tests" title="Permalink to this headline"></a></h2>
299+
<p><a class="reference external" href="https://docs.pytest.org/">pytest</a> is used to run unit and integration tests,
300+
under the <code class="docutils literal notranslate"><span class="pre">tests/</span></code> directory. If you add new functionality, you should also add
301+
tests to cover it. You can run the tests locally with <code class="docutils literal notranslate"><span class="pre">py.test</span> <span class="pre">tests/</span></code></p>
302+
</div>
303+
<div class="section" id="building-documentation">
304+
<h2>Building documentation<a class="headerlink" href="#building-documentation" title="Permalink to this headline"></a></h2>
305+
<p><a class="reference external" href="https://www.sphinx-doc.org/">sphinx</a> is used to write and maintain documentation, under
306+
the <code class="docutils literal notranslate"><span class="pre">docs/</span></code> directory. If you add any new functionality, you should write documentaiton
307+
for it as well. A mix of <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html">reStructuredText</a>
308+
and <a class="reference external" href="https://myst-parser.readthedocs.io">MyST Markdown</a> is used to write our documentation,
309+
although we would like to migrate purely to MyST markdown in the future.</p>
310+
<ol>
311+
<li><p>Install the packages needed to build the documentation</p>
312+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pip install -r docs/doc-requirements.txt
313+
</pre></div>
314+
</div>
315+
</li>
316+
<li><p>Build the documentation by using <code class="docutils literal notranslate"><span class="pre">make</span></code> inside the <code class="docutils literal notranslate"><span class="pre">docs</span></code> folder. This will
317+
internally call <code class="docutils literal notranslate"><span class="pre">sphinx</span></code></p>
318+
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span> docs
319+
make html
220320
</pre></div>
221321
</div>
222322
</li>
323+
<li><p>Preview the documentation by opening <code class="docutils literal notranslate"><span class="pre">_build/html/index.html</span></code> file in
324+
your browser. From inside the <code class="docutils literal notranslate"><span class="pre">docs</span></code> folder, you can run either
325+
<code class="docutils literal notranslate"><span class="pre">open</span> <span class="pre">_build/html/index.html</span></code> (on MacOS) or <code class="docutils literal notranslate"><span class="pre">xdg-open</span> <span class="pre">_build/html/index.html</span></code>
326+
to quickly open the file in the browser.</p></li>
327+
<li><p>You can run <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">html</span></code> again after making further changes to see their
328+
effects.</p></li>
223329
</ol>
224330
</div>
225331
</div>
@@ -228,12 +334,32 @@ <h2>Setup<a class="headerlink" href="#setup" title="Permalink to this headline">
228334
</div>
229335

230336

231-
<div class='prev-next-bottom'>
232337

233-
<a class='left-prev' id="prev-link" href="install.html" title="previous page">Installation</a>
234-
<a class='right-next' id="next-link" href="topic/automatic-merging.html" title="next page">Automatic Merging Behavior</a>
235338

236-
</div>
339+
340+
341+
<div class='prev-next-bottom'>
342+
343+
<div id="prev">
344+
<a class="left-prev" href="install.html" title="previous page">
345+
<i class="prevnext-label fas fa-angle-left"></i>
346+
<div class="prevnext-info">
347+
<p class="prevnext-label">previous</p>
348+
<p class="prevnext-title">Installation</p>
349+
</div>
350+
</a>
351+
</div>
352+
<div id="next">
353+
<a class="right-next" href="topic/automatic-merging.html" title="next page">
354+
<div class="prevnext-info">
355+
<p class="prevnext-label">next</p>
356+
<p class="prevnext-title">Automatic Merging Behavior</p>
357+
</div>
358+
<i class="prevnext-label fas fa-angle-right"></i>
359+
</a>
360+
</div>
361+
362+
</div>
237363

238364
</div>
239365
</div>

0 commit comments

Comments
 (0)