diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 287696db..d005fff1 100644 --- a/.github/workflows/docs.yml +++ b/.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 diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..b165d7e5 --- /dev/null +++ b/.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 diff --git a/README.md b/README.md index da2a2575..f112fde2 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # [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) @@ -9,11 +9,11 @@ `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) diff --git a/docs/_static/link_gen/link.js b/docs/_static/link_gen/link.js index f5e11e2d..ef67e1c4 100644 --- a/docs/_static/link_gen/link.js +++ b/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; diff --git a/docs/conf.py b/docs/conf.py index baa0be9a..c21428a1 100644 --- a/docs/conf.py +++ b/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. diff --git a/docs/index.md b/docs/index.md index 799a7bab..e52903be 100644 --- a/docs/index.md +++ b/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 diff --git a/docs/link.rst b/docs/link.rst index c7516897..14836faa 100644 --- a/docs/link.rst +++ b/docs/link.rst @@ -12,41 +12,42 @@ Use the following form to create your own ``nbgitpuller`` links. .. raw:: html -
+
-
+
-
+
-
+
-
@@ -175,6 +176,11 @@ Use the following form to create your own ``nbgitpuller`` links.



+ + **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 diff --git a/docs/topic/url-options.rst b/docs/topic/url-options.rst index 200d3be1..7a6a0f5b 100644 --- a/docs/topic/url-options.rst +++ b/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 `_ + 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 ```` should be ``my-repository/index.ipynb``, **not** ``index.ipynb``. - The `link generator `_ + The :doc:`link generator <../link>` takes care of all of this for you, so it is recommended to use that.