diff --git a/.github/workflows/chatops.yaml b/.github/workflows/chatops.yaml new file mode 100644 index 00000000..bca34728 --- /dev/null +++ b/.github/workflows/chatops.yaml @@ -0,0 +1,34 @@ +#./github/workflows/chatops.yaml +name: Chatops +on: [issue_comment] # issues and PRs are equivalent in terms of comments for the GitHub API + +jobs: + trigger-chatops: + # Make sure the comment is on a PR, and contains the command "/binder" + if: (github.event.issue.pull_request != null) && contains(github.event.comment.body, '/binder') + runs-on: ubuntu-latest + steps: + # Use the GitHub API to: + # (1) Get the branch name of the PR that has been commented on with "/binder" + # (2) make a comment on the PR with the binder badge + - name: comment on PR with Binder link + uses: actions/github-script@v1 + with: + github-token: ${{secrets.GITHUB_TOKEN}} + script: | + // Get the branch name + github.pulls.get({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: context.payload.issue.number + }).then( (pr) => { + + // use the branch name to make a comment on the PR with a Binder badge + var BRANCH_NAME = pr.data.head.ref + github.issues.createComment({ + issue_number: context.payload.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: `[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/${context.repo.owner}/${context.repo.repo}/${BRANCH_NAME}) :point_left: Launch a binder notebook on this branch` + }) + }) diff --git a/Makefile b/Makefile deleted file mode 100644 index d4bb2cbb..00000000 --- a/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -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) diff --git a/README.md b/README.md index dc085d6f..15b705bf 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,43 @@ # NumPy tutorials +[![Binder](http://mybinder.org/badge_logo.svg)](http://mybinder.org/v2/gh/numpy/numpy-tutorials/master/content) + This set of tutorials and educational materials is being developed, -IT IS NOT YET INTEGRATED IN THE HTML DOCS AT https://www.numpy.org/devdocs/ +IT IS NOT INTEGRATED IN THE HTML DOCS AT https://www.numpy.org/devdocs/ The goal of this repository is to provide high-quality resources by the -NumPy project, both for self-learning and for teaching classes with. +NumPy project, both for self-learning and for teaching classes with. If you're +interested in adding your own content, check the [Contributing](#contributing) +section. + +To open a live version of the content, click the **launch Binder** button above. +To download a local copy of the `.ipynb` files, you can either +[clone this repository](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) +or navigate to any of the documents listed below and download it individually. + +## Content + +1. [Tutorial: Linear algebra on n-dimensional arrays](content/tutorial-svd.ipynb) +2. [Tutorial: CS231n Python Tutorial With Google Colab](content/cs231_tutorial.ipynb) ## Contributing We very much welcome contributions! If you have an idea or proposal for a new -tutorial, please open an issue with an outline. +tutorial, please [open an issue](https://github.com/numpy/numpy-tutorials/issues) +with an outline. After you have decided on a topic and approach, submit your +notebook file via a [pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests). +For more information about GitHub and its workflow, you can see +[this document](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests). -## Jupyter Notebooks +Don’t worry if English is not your first language, or if you can only come up +with a rough draft. Open source is a community effort. Do your best – we’ll help +fix issues. + +Images and real-life data make text more engaging and powerful, but be sure what +you use is appropriately licensed and available. Here again, even a rough idea +for artwork can be polished by others. + +### Why Jupyter Notebooks? The choice of Jupyter Notebook in this repo instead of the usual format ([reStructuredText, through Sphinx](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html)) @@ -22,44 +48,22 @@ used in the main NumPy documentation has two reasons: * rST may present a barrier for some people who might otherwise be very interested in contributing tutorial material. -## Generating the "site" - -Sphinx is configured with the appropriate extensions to execute the notebooks -and generated webpages from them. To accomplish this from a fresh repo: +### Adding your own tutorials -1. Install the dependencies: from a terminal, run - - ``` - pip install -r requirements.txt - ``` - - To execute the notebooks, you'll also need to install the dependencies for - the tutorial(s) themselves: - - ``` - pip install -r content/requirements.txt - ``` - -2. Build and view: from your terminal, run - - ``` - make html && _build/html/index.html - ``` - -## Adding your own tutorials - -If you have your own tutorial in the form of a Jupyter notebook and you'd like +If you have your own tutorial in the form of a Jupyter notebook (a `.ipynb` +file) and you'd like to try it out on the site: 1. Add your notebook to the `content/` directory -2. Update `content/requirements.txt` with the dependencies for your tutorial -3. Update the `toctree` in `index.rst` to include your new entry -4. Update the attribution section (below) to credit the original tutorial - author. +2. Update the `environment.yml` file with the dependencies for your tutorial +(only if you add new dependencies) +3. Update this `README.md` to include your new entry +4. Update the attribution section (below) to credit the original tutorial +author. -## Attribution +### Attribution - - The [cs231n][cs231] tutorial is by [@jcjohnson][jj]. The full tutorial in + - The cs231n tutorial is by [@jcjohnson][jj]. The full tutorial in its original form is linked via [numpy.org][learn]. - The SVD tutorial is by [@melissawm][mwm]. The full tutorial is available via the [tutorials page][np_tutorials] of the official NumPy documentation. @@ -68,14 +72,17 @@ to try it out on the site: [mwm]: https://github.com/melissawm [np_tutorials]: https://numpy.org/devdocs/user/tutorials_index.html -## Useful links +## Useful links and resources -The following may be useful: +The following links may be useful: -- [NumPy documentation team meetings](https://hackmd.io/oB_boakvRqKR-_2jRV-Qjg?both) +- [NumPy Code of Conduct](https://numpy.org/doc/stable/dev/conduct/code_of_conduct.html) +- [Main NumPy documentation](https://numpy.org/doc/stable/) +- [NumPy documentation team meeting notes](https://hackmd.io/oB_boakvRqKR-_2jRV-Qjg?both) - [NEP 44 - Restructuring the NumPy documentation](https://numpy.org/neps/nep-0044-restructuring-numpy-docs.html) - [Blog post - Documentation as a way to build Community](https://labs.quansight.org/blog/2020/03/documentation-as-a-way-to-build-community/) -- Note that regular documentation issues for NumPy can be found in the - [main NumPy repository](https://github.com/numpy/numpy/issues) (see the - `Documentation` labels (2x) there) + +Note that regular documentation issues for NumPy can be found in the [main NumPy +repository](https://github.com/numpy/numpy/issues) (see the `Documentation` +labels there). diff --git a/_static/numpy_logo.png b/_static/numpy_logo.png deleted file mode 100644 index af8cbe32..00000000 Binary files a/_static/numpy_logo.png and /dev/null differ diff --git a/_templates/customsidebar.html b/_templates/customsidebar.html deleted file mode 100644 index 245d6b7d..00000000 --- a/_templates/customsidebar.html +++ /dev/null @@ -1,10 +0,0 @@ -

Source

- - - -
- - diff --git a/_templates/globaltoc.html b/_templates/globaltoc.html deleted file mode 100644 index 22b1d48f..00000000 --- a/_templates/globaltoc.html +++ /dev/null @@ -1,2 +0,0 @@ -

{{ _('All Tutorials') }}

-{{ toctree() }} diff --git a/_templates/indexsidebar.html b/_templates/indexsidebar.html deleted file mode 100644 index 4707fc0e..00000000 --- a/_templates/indexsidebar.html +++ /dev/null @@ -1,5 +0,0 @@ -

Resources

- diff --git a/conf.py b/conf.py deleted file mode 100644 index 60f86ff1..00000000 --- a/conf.py +++ /dev/null @@ -1,79 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - - -# -- Project information ----------------------------------------------------- - -project = 'NumPy Tutorials' -copyright = '2020, NumPy Community' -author = 'NumPy Community' - -# The full version, including alpha/beta/rc tags -# release = '0.0.1-dev' - - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - "myst_nb", -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.md'] - -# -- Notebook execution options --------------------------------------------- - -# Valid options: "off", "force", "auto", and "cache" -jupyter_execute_notebooks = "auto" - - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -#html_theme = 'pyramid' -html_theme = 'sphinx_book_theme' -html_theme_options = { - "launch_buttons": { - "binderhub_url": "https://mybinder.org/v2/gh/numpy/numpy-tutorials/master" - }, - "repository_url": "https://github.com/numpy/numpy-tutorials", - "repository_branch": "master", - "path_to_docs": "content", - } - -# 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'] -html_title = 'NumPy Tutorials' -html_sidebars = {'index': ['indexsidebar.html'], - '**': ['localtoc.html', 'customsidebar.html', 'globaltoc.html']} - -html_copy_source = True -#html_domain_indices = False -#html_file_suffix = '.html' -#html_sourcelink_suffix = [ '.ipynb', '.py' ] - diff --git a/content/requirements.txt b/content/requirements.txt deleted file mode 100644 index a9e2534f..00000000 --- a/content/requirements.txt +++ /dev/null @@ -1,3 +0,0 @@ -numpy -matplotlib -scipy diff --git a/environment.yml b/environment.yml new file mode 100644 index 00000000..d9f5c65f --- /dev/null +++ b/environment.yml @@ -0,0 +1,7 @@ +name: numpy-tutorials +channels: + - conda-forge +dependencies: + - numpy + - scipy + - matplotlib diff --git a/index.rst b/index.rst deleted file mode 100644 index 07dd6ac4..00000000 --- a/index.rst +++ /dev/null @@ -1,35 +0,0 @@ -.. numpy_tutorials_notebook_demo documentation master file, created by - sphinx-quickstart on Thu Jun 4 14:15:17 2020. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -NumPy Tutorials -=============== - -The goal of this repository is to provide high-quality resources by the NumPy project, both for self-learning and for teaching classes with. - -This set of tutorials and educational materials is being developed, IT IS NOT YET INTEGRATED IN THE HTML DOCS AT https://www.numpy.org/devdocs/ - -You can contribute by submitting a `pull request on GitHub `_ with your Jupyter Notebook file. - -Resources ---------- - -- `NumPy `_ -- `Main NumPy Documentation `_ -- `NumPy Code of Conduct `_ -- `How to contribute to the NumPy Documentation `_ -- `NEP 44 - Restructuring the NumPy Documentation `_ - -Content -======= - -All tutorials are downloadable as ``.ipynb`` files. Alternatively, you can -download a ``.py`` file, with all the notebook content in play text. - -.. toctree:: - :maxdepth: 1 - - content/cs231_tutorial - content/tutorial-svd - diff --git a/make.bat b/make.bat deleted file mode 100644 index 2119f510..00000000 --- a/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=. -set BUILDDIR=_build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index 9304378c..00000000 --- a/requirements.txt +++ /dev/null @@ -1,6 +0,0 @@ -sphinx==2.4.4 -jupyter -# Executablebooks -myst-nb -# Theme -sphinx-book-theme