Merge pull request #297 from minrk/rtd

migrate docs to RTD

Author: consideRatio

.github/workflows/docs.yml

@@ -39,31 +39,3 @@ jobs:
         run: |
           cd docs
           make linkcheck
-
-  build-and-publish:
-    runs-on: ubuntu-22.04
-
-    permissions:
-      # required to push to the gh-pages branch
-      contents: write
-
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          python-version: "3.11"
-
-      - 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

.readthedocs.yaml

@@ -0,0 +1,17 @@
+# Configuration on how ReadTheDocs (RTD) builds our documentation
+# ref: https://readthedocs.org/projects/nbgitpuller/
+# ref: https://docs.readthedocs.io/en/stable/config-file/v2.html
+#
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.10"
+
+python:
+  install:
+    - requirements: docs/doc-requirements.txt

README.md

@@ -1,19 +1,19 @@
 # [nbgitpuller](https://github.com/jupyterhub/nbgitpuller)
 
 [![GitHub Workflow Status - Test](https://img.shields.io/github/workflow/status/jupyterhub/nbgitpuller/Tests?logo=github&label=tests)](https://github.com/jupyterhub/nbgitpuller/actions)
-[![CircleCI build status](https://img.shields.io/circleci/build/github/jupyterhub/nbgitpuller?logo=circleci&label=docs)](https://circleci.com/gh/jupyterhub/nbgitpuller)
+[![Documentation Status](https://readthedocs.org/projects/nbgitpuller/badge/?version=latest)](https://nbgitpuller.readthedocs.io/en/latest/?badge=latest)
 [![](https://img.shields.io/pypi/v/nbgitpuller.svg?logo=pypi)](https://pypi.python.org/pypi/nbgitpuller)
 [![GitHub](https://img.shields.io/badge/issue_tracking-github-blue?logo=github)](https://github.com/jupyterhub/nbgitpuller/issues)
 [![Discourse](https://img.shields.io/badge/help_forum-discourse-blue?logo=discourse)](https://discourse.jupyter.org/c/jupyterhub)
 [![Gitter](https://img.shields.io/badge/social_chat-gitter-blue?logo=gitter)](https://gitter.im/jupyterhub/jupyterhub)
 
 `nbgitpuller` lets you distribute content in a git repository to your students
 by having them click a simple link. [Automatic
-merging](https://jupyterhub.github.io/nbgitpuller/topic/automatic-merging.html)
+merging](https://nbgitpuller.readthedocs.io/topic/automatic-merging.html)
 ensures that your students are never exposed to `git` directly. It is primarily
 used with a JupyterHub, but can also work on students' local computers.
 
-See [the documentation](https://jupyterhub.github.io/nbgitpuller) for more
+See [the documentation](https://nbgitpuller.readthedocs.io) for more
 information.
 
 ## Installation
@@ -24,10 +24,12 @@ pip install nbgitpuller
 
 ## Example
 
-This example shows how to use the [nbgitpuller link generator](https://jupyterhub.github.io/nbgitpuller/link)
+This example shows how to use the [nbgitpuller link generator]
 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
+[nbgitpuller link generator]: https://nbgitpuller.readthedocs.io/link
+
+1. The nbgitpuller link generator GUI is used to create a
    link.
 
    ![](https://raw.githubusercontent.com/jupyterhub/nbgitpuller/9f380a933335f0f069b6e2f9965ed78c3abcce7a/docs/_static/nbgitpuller-link-generator.png)

docs/_static/link_gen/link.js

@@ -185,7 +185,7 @@ function displayLink() {
                 hubUrl, urlPath, repoUrl, branch
             );
         } else if (activeTab === "tab-auth-binder"){
-            // FIXME: userName parsing using new URL(...) assumes a 
+            // FIXME: userName parsing using new URL(...) assumes a
             // HTTP based repoUrl. Does it make sense to create a
             // BinderHub link for SSH URLs? Then let's fix this parsing.
             var userName = new URL(repoUrl).pathname.split('/')[1];
@@ -248,7 +248,7 @@ function render() {
 /**
  * Entry point
  */
-function main() {
+function linkMain() {
     // Hook up any changes in form elements to call render()
     document.querySelectorAll('#linkgenerator input[type="radio"]').forEach(
         function (element) {
@@ -265,16 +265,15 @@ function main() {
 
     // Activate tabs based on search parameters
     var params = new URL(window.location).searchParams;
-    if (params.get("tab")) {
-      if (params.get("tab") === "binder") {
-        $("#tab-auth-binder").click()
-      } else if (params.get("tab") === "canvas") {
-        $("#tab-auth-canvas").click()
-      }
+    switch(params.get("tab")) {
+      case "binder":
+        $("#tab-auth-binder").click();
+        break;
+      case "canvas":
+        $("#tab-auth-canvas").click();
+        break;
     }
 
     // Do an initial render, to make sure our disabled / enabled properties are correctly set
     render();
 }
-
-window.onload = main;

docs/conf.py

@@ -53,7 +53,7 @@ def setup(app):
 #
 # 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
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/index.md

@@ -10,9 +10,7 @@ It is commonly used to distribute content to multiple users of a JupyterHub, tho
 
 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.
+1. The [nbgitpuller link generator](link) is used to create a link.
 
    ```{image} _static/nbgitpuller-link-generator.png
 

docs/link.rst

@@ -12,41 +12,42 @@ Use the following form to create your own ``nbgitpuller`` links.
 
 .. raw:: html
 
-   <div class="container full-width">
+   <div class="container">
        <form id="linkgenerator" class="form needs-validation">
 
            <div class="form-group">
 
              <ul class="nav nav-tabs justify-content-end" role="tablist">
-               <li class="nav-item">
-                 <a class="nav-link active" id="tab-auth-default" data-toggle="tab" role="tab" href="#auth-default" aria-controls="auth-default" onclick="changeTab(this)">
+               <li class="nav-item" role="presentation">
+                 <button class="nav-link active" id="tab-auth-default" data-bs-toggle="tab" data-bs-target="#auth-default" type="button" role="tab" aria-controls="auth-default"  aria-selected="true" onclick="changeTab(this)">
                    <small>JupyterHub</small>
-                 </a>
+                 </button>
                </li>
-               <li class="nav-item">
-                 <a class="nav-link" id="tab-auth-canvas" data-toggle="tab" role="tab" href="#auth-canvas" aria-controls="auth-canvas" onclick="changeTab(this)">
+               <li class="nav-item" role="presentation">
+                 <button class="nav-link" id="tab-auth-canvas" data-bs-target="#auth-canvas" data-bs-toggle="tab" type="button" role="tab" aria-controls="auth-canvas"
+                 aria-selected="false" onclick="changeTab(this)">
                    <small>Launch from Canvas</small>
-                 </a>
+                 </button>
                </li>
-               <li class="nav-item">
-                 <a class="nav-link" id="tab-auth-binder" data-toggle="tab" role="tab" href="#auth-binder" aria-controls="auth-binder" onclick="changeTab(this)">
+               <li class="nav-item" role="presentation">
+                 <button class="nav-link" id="tab-auth-binder" data-bs-toggle="tab" data-bs-target="#auth-binder" type="button" role="tab" aria-controls="auth-binder"
+                 aria-selected="false" onclick="changeTab(this)">
                    <small>Binder</small>
-                 </a>
+                 </button>
                </li>
              </ul>
 
              <div class="tab-content">
-               <div class="tab-pane fade show active" id="auth-default" role="tabpanel" aria-labelledby="tab-auth-default">
+               <div class="tab-pane fade show active" id="auth-default" role="tabpanel" aria-labelledby="tab-auth-default" tabindex="0">
                  <input type="text" readonly class="form-control form-control" id="default-link" name="auth-default-link" placeholder="Generated link appears here...">
                </div>
-               <div class="tab-pane fade" id="auth-canvas" role="tabpanel" aria-labelledby="tab-auth-canvas">
+               <div class="tab-pane fade" id="auth-canvas" role="tabpanel" aria-labelledby="tab-auth-canvas"  tabindex="0">
                  <input type="text" readonly class="form-control form-control" id="canvas-link" name="auth-canvas-link" placeholder="Generated canvas 'external app' link appears here...">
                </div>
-               <div class="tab-pane fade" id="auth-binder" role="tabpanel" aria-labelledby="tab-auth-binder">
+               <div class="tab-pane fade" id="auth-binder" role="tabpanel" aria-labelledby="tab-auth-binder"  tabindex="0">
                  <input type="text" readonly class="form-control form-control" id="binder-link" name="auth-binder-link" placeholder="Generated Binder link appears here...">
                </div>
              </div>
-             </ul>
            </div>
 
            <div class="form-group row">
@@ -175,6 +176,11 @@ Use the following form to create your own ``nbgitpuller`` links.
      </div>
      <br /><br /><br />
 
+     <script type="text/javascript">
+         // load link javascript on page load
+         window.addEventListener("load", linkMain);
+     </script>
+
 
 **Pre-populating some fields in the link generator**
 
@@ -183,19 +189,19 @@ 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
+* ``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
+    https://nbgitpuller.readthedocs.io/link.html?hub=https://datahub.berkeley.edu
 
 
 **Activating a tab when someone lands on this page**
 
 You can also activate one of the tabs in the form above by default when a user lands
-on this page. To do so, use the ``tab=`` REST parameter. Here are the possible values:
+on this page. To do so, use the ``tab=`` query parameter. Here are the possible values:
 
 * ``?tab=binder`` - activates the Binder tab
-* ``?tab=canvas`` - activates the Canvas tab.
+* ``?tab=canvas`` - activates the Canvas tab

docs/topic/url-options.rst

@@ -7,7 +7,7 @@ Options in an nbgitpuller URL
 .. note::
 
    If you just want to generate an nbgitpuller link, we highly
-   recommend just using the `link generator <https://jupyterhub.github.io/nbgitpuller/link>`_
+   recommend just using the :doc:`link generator <../link>`
 
 Most aspects of the nbgitpuller student experience can be configured
 with various options in the nbgitpuller URL. This page documents
@@ -41,12 +41,12 @@ the file to be opened in.
    the local repository directory too, otherwise nbgitpuller can not
    find the file.
 
-   For example, if the repository you are cloning is 
+   For example, if the repository you are cloning is
    ``https://github.com/my-user/my-repository``, and the file you want
    your students to see is ``index.ipynb``, then ``<full-path-to-file>``
    should be ``my-repository/index.ipynb``, **not** ``index.ipynb``.
 
-   The `link generator <https://jupyterhub.github.io/nbgitpuller/link>`_
+   The :doc:`link generator <../link>`
    takes care of all of this for you, so it is recommended to use that.