From de3531df22e65bb1649a83bf95cd7afe0d4e1aa9 Mon Sep 17 00:00:00 2001 From: Anderson Banihirwe Date: Fri, 14 Jan 2022 18:28:21 -0700 Subject: [PATCH 1/2] Update README --- README.md | 19 +++++-------------- 1 file changed, 5 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index cd6fdd0..9a4f502 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,10 @@ # jupyter-forward -- [jupyter-forward](#jupyter-forward) - - [Badges](#badges) - - [Overview](#overview) - - [Installation](#installation) - -## Badges - -| CI | [![GitHub Workflow Status][github-ci-badge]][github-ci-link] [![GitHub Workflow Status][github-lint-badge]][github-lint-link] [![Code Coverage Status][codecov-badge]][codecov-link] | -| :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | -| **Docs** | [![Documentation Status][rtd-badge]][rtd-link] | -| **Package** | [![Conda][conda-badge]][conda-link] [![PyPI][pypi-badge]][pypi-link] | -| **License** | [![License][license-badge]][repo-link] | +| CI | [![GitHub Workflow Status][github-ci-badge]][github-ci-link] [![Code Coverage Status][codecov-badge]][codecov-link] | +| :---------- | :-----------------------------------------------------------------------------------------------------------------: | +| **Docs** | [![Documentation Status][rtd-badge]][rtd-link] | +| **Package** | [![Conda][conda-badge]][conda-link] [![PyPI][pypi-badge]][pypi-link] | +| **License** | [![License][license-badge]][repo-link] | ## Overview @@ -39,9 +32,7 @@ conda install -c conda-forge jupyter-forward See [documentation](https://jupyter-forward.readthedocs.io) for more information. [github-ci-badge]: https://img.shields.io/github/workflow/status/NCAR/jupyter-forward/CI?label=CI&logo=github&style=for-the-badge -[github-lint-badge]: https://img.shields.io/github/workflow/status/NCAR/jupyter-forward/linting?label=linting&logo=github&style=for-the-badge [github-ci-link]: https://github.com/NCAR/jupyter-forward/actions?query=workflow%3ACI -[github-lint-link]: https://github.com/NCAR/jupyter-forward/actions?query=workflow%3Alinting [codecov-badge]: https://img.shields.io/codecov/c/github/NCAR/jupyter-forward.svg?logo=codecov&style=for-the-badge [codecov-link]: https://codecov.io/gh/NCAR/jupyter-forward [rtd-badge]: https://img.shields.io/readthedocs/jupyter-forward/latest.svg?style=for-the-badge From 54a054c317607c095d0bc9e8e25ba3e057631d5c Mon Sep 17 00:00:00 2001 From: Anderson Banihirwe Date: Fri, 14 Jan 2022 19:02:35 -0700 Subject: [PATCH 2/2] Rearrange docs + Use furo theme --- CONTRIBUTING.md | 150 ++++++++++++++++++ docs/environment.yml | 8 +- docs/source/conf.py | 108 ++----------- docs/source/contributing.md | 3 + docs/source/dev-guide.md | 15 -- docs/source/explanation/index.md | 1 + docs/source/how-to/index.md | 10 ++ docs/source/how-to/install-jupyter-forward.md | 33 ++++ docs/source/index.md | 35 ++-- docs/source/installation.md | 13 -- docs/source/{usage.md => reference/index.md} | 0 .../{examples.md => tutorials/index.md} | 2 +- readthedocs.yml | 10 +- 13 files changed, 245 insertions(+), 143 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 docs/source/contributing.md delete mode 100644 docs/source/dev-guide.md create mode 100644 docs/source/explanation/index.md create mode 100644 docs/source/how-to/index.md create mode 100644 docs/source/how-to/install-jupyter-forward.md delete mode 100644 docs/source/installation.md rename docs/source/{usage.md => reference/index.md} (100%) rename docs/source/{examples.md => tutorials/index.md} (99%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ce1f122 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,150 @@ +# Contributing Guide + +Interested in helping build jupyter-forward? Have code from your work that +you believe others will find useful? Have a few minutes to tackle an issue? + +Contributions are highly welcomed and appreciated. Every little help counts, +so do not hesitate! + +The following sections cover some general guidelines +regarding development in jupyter-forward for maintainers and contributors. +Nothing here is set in stone and can't be changed. +Feel free to suggest improvements or changes in the workflow. + +## Feature requests and feedback + +We'd also like to hear about your propositions and suggestions. Feel free to +submit them as issues on [jupyter-forward's GitHub issue tracker](https://github.com/NCAR/jupyter-forward) and: + +- Explain in detail how they should work. +- Keep the scope as narrow as possible. This will make it easier to implement. + +## Report bugs + +Report bugs for jupyter-forward in the [issue tracker](https://github.com/NCAR/jupyter-forward). + +If you are reporting a bug, please include: + +- Your operating system name and version. +- Any details about your local setup that might be helpful in troubleshooting, + specifically the Python interpreter version, installed libraries, and jupyter-forward + version. +- Detailed steps to reproduce the bug. + +If you can write a demonstration test that currently fails but should pass +(xfail), that is a very useful commit to make as well, even if you cannot +fix the bug itself. + +## Fix bugs + +Look through the [GitHub issues for bugs](https://github.com/NCAR/jupyter-forward/labels/type:%20bug). + +Talk to developers to find out how you can fix specific bugs. + +## Write documentation + +jupyter-forward could always use more documentation. What exactly is needed? + +- More complementary documentation. Have you perhaps found something unclear? +- Docstrings. There can never be too many of them. +- Blog posts, articles and such -- they're all very appreciated. + +You can also edit documentation files directly in the GitHub web interface, +without using a local copy. This can be convenient for small fixes. + +Build the documentation locally with the following command: + +```bash +$ make docs +``` + +## Preparing Pull Requests + +1. Fork the [jupyter-forward GitHub repository](https://github.com/NCAR/jupyter-forward). + +2. Clone your fork locally using [git](https://git-scm.com/), connect your repository + to the upstream (main project), and create a branch:: + + ```bash + $ git clone git@github.com:YOUR_GITHUB_USERNAME/jupyter-forward.git + $ cd jupyter-forward + $ git remote add upstream git@github.com:NCAR/jupyter-forward.git + ``` + + now, to fix a bug or add feature create your own branch off "master": + + ```bash + $ git checkout -b your-bugfix-feature-branch-name master + ``` + + If you need some help with Git, follow this quick start + guide: https://git.wiki.kernel.org/index.php/QuickStart + +3. Install dependencies into a new conda environment:: + + ```bash + $ conda env update -f ci/environment.yml + $ conda activate jupyter-forward-dev + ``` + +4. Make an editable install of jupyter-forward by running:: + + ```bash + $ python -m pip install -e . + ``` + +5. Install `pre-commit `\_ hooks on the jupyter-forward repo:: + + ```bash + $ pre-commit install + ``` + + Afterwards `pre-commit` will run whenever you commit. + + [pre-commit](https://pre-commit.com) is a framework for managing and maintaining multi-language pre-commit hooks to ensure code-style and code formatting is consistent. + + Now you have an environment called `jupyter-forward-dev` that you can work in. + You’ll need to make sure to activate that environment next time you want + to use it after closing the terminal or your system. + +6. (Optional) Run all the tests + + Now running tests is as simple as issuing this command:: + + ```bash + $ pytest + ``` + + This command will run tests via the `pytest` tool. + +7. Commit and push once your tests pass and you are happy with your change(s):: + + When committing, `pre-commit` will re-format the files if necessary. + + ```bash + $ git commit -a -m "" + $ git push -u + ``` + +8. Finally, submit a pull request through the GitHub website using this data:: + + ```console + head-fork: YOUR_GITHUB_USERNAME/jupyter-forward + compare: your-branch-name + + base-fork: NCAR/jupyter-forward + base: master # if it's a bugfix or feature + ``` + +````{note} +In some cases you may want to create a local virtual machine (VM) to simulate a remote machine. This is not necessary, but it is recommended. You can use the provided [vagrant file](https://www.vagrantup.com/) to create a VM. From the root directory of the jupyter-forward repository, run the following command to create a VM:: + ```bash + $ vagrant up + $ vagrant ssh-config > vagrant-ssh + $ ssh -F vagrant-ssh default + $ jupyter-forward vagrant@127.0.0.1:2222 --identity ./.vagrant/machines/default/virtualbox/private_key +```` + +``` + +``` diff --git a/docs/environment.yml b/docs/environment.yml index 98a5619..ad81f47 100644 --- a/docs/environment.yml +++ b/docs/environment.yml @@ -3,14 +3,14 @@ channels: - conda-forge - nodefaults dependencies: + - furo - myst-nb - pip - - python=3.8 - - sphinx-book-theme >= 0.0.38 + - python=3.9 - sphinx-copybutton - - sqlalchemy==1.3.12 + - sphinx-inline-tabs + - sqlalchemy - pip: - sphinxext-opengraph - - sphinx-comments - -r ../requirements.txt - -e .. diff --git a/docs/source/conf.py b/docs/source/conf.py index a3fa4ef..90f99cb 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,38 +1,8 @@ -# -# complexity documentation build configuration file, created by -# sphinx-quickstart on Tue Jul 9 22:26:36 2013. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - import datetime -import os -import sys import jupyter_forward -# 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. -# sys.path.insert(0, os.path.abspath('.')) - -cwd = os.getcwd() -parent = os.path.dirname(cwd) -sys.path.insert(0, parent) - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -# needs_sphinx = '1.0' - -# 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.ext.autodoc', 'sphinx.ext.viewcode', @@ -41,40 +11,32 @@ 'sphinx.ext.intersphinx', 'sphinx.ext.extlinks', 'sphinx.ext.intersphinx', - # 'IPython.sphinxext.ipython_console_highlighting', - # 'IPython.sphinxext.ipython_directive', 'sphinx.ext.napoleon', - 'myst_parser', + 'myst_nb', 'sphinxext.opengraph', 'sphinx_copybutton', - 'sphinx_comments', + 'sphinx_inline_tabs', ] + autodoc_member_order = 'groupwise' # MyST config myst_enable_extensions = ['amsmath', 'colon_fence', 'deflist', 'html_image'] -myst_url_schemes = ('http', 'https', 'mailto') +myst_url_schemes = ['http', 'https', 'mailto'] -comments_config = { - 'utterances': {'repo': 'NCAR/jupyter-forward', 'optional': 'config', 'label': '💬 comment'}, - 'hypothesis': False, -} +jupyter_execute_notebooks = 'cache' +execution_timeout = 600 +execution_allow_errors = True # sphinx-copybutton configurations copybutton_prompt_text = r'>>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: ' copybutton_prompt_is_regexp = True -extlinks = { - 'issue': ('https://github.com/NCAR/jupyter-forward/issues/%s', 'GH#'), - 'pr': ('https://github.com/NCAR/jupyter-forward/pull/%s', 'GH#'), -} -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - # Autosummary pages will be generated by sphinx-autogen instead of sphinx-build autosummary_generate = [] autodoc_typehints = 'none' +autodoc_preserve_defaults = True # Napoleon configurations @@ -85,11 +47,8 @@ napoleon_preprocess_types = True -# The suffix of source filenames. -# source_suffix = '.rst' - -# The encoding of source files. -# source_encoding = 'utf-8-sig' +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] # The master toctree document. master_doc = 'index' @@ -121,7 +80,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'sphinx_book_theme' +html_theme = 'furo' html_title = '' html_context = { @@ -130,53 +89,15 @@ 'github_version': 'main', 'doc_path': 'docs', } -html_theme_options = dict( - # analytics_id='' this is configured in rtfd.io - # canonical_url="", - repository_url='https://github.com/NCAR/jupyter-forward', - repository_branch='main', - path_to_docs='docs', - use_edit_page_button=True, - use_repository_button=True, - use_issues_button=True, - home_page_in_toc=False, - github_url='https://github.com/NCAR/jupyter-forward', - twitter_url='https://twitter.com/NCARXDev', - extra_navbar='', - navbar_footer_text='', - extra_footer="""Theme by the Executable Book Project""", -) +html_theme_options = dict() # The name of an image file (relative to this directory) to place at the top # of the sidebar. html_logo = '../_static/images/NSF_4-Color_bitmap_Logo.png' - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -# html_favicon = None - -# 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'] -# Sometimes the savefig directory doesn't exist and needs to be created -# https://github.com/ipython/ipython/issues/8733 -# becomes obsolete when we can pin ipython>=5.2; see ci/requirements/doc.yml -# ipython_savefig_dir = os.path.join( -# os.path.dirname(os.path.abspath(__file__)), '_build', 'html', '_static' -# ) - -# savefig_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'source', '_static') - -# os.makedirs(ipython_savefig_dir, exist_ok=True) -# os.makedirs(savefig_dir, exist_ok=True) - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. html_last_updated_fmt = '%b %d, %Y' @@ -214,8 +135,5 @@ ) ] -ipython_warning_is_error = False -ipython_execlines = [] - -intersphinx_mapping = {} +intersphinx_mapping = {'python': ('https://docs.python.org/3/', None)} diff --git a/docs/source/contributing.md b/docs/source/contributing.md new file mode 100644 index 0000000..8ece9d8 --- /dev/null +++ b/docs/source/contributing.md @@ -0,0 +1,3 @@ +```{include} ../../CONTRIBUTING.md + +``` diff --git a/docs/source/dev-guide.md b/docs/source/dev-guide.md deleted file mode 100644 index ab17a9a..0000000 --- a/docs/source/dev-guide.md +++ /dev/null @@ -1,15 +0,0 @@ -# Development Guide - -## Provisioning the vagrant VM environment - -```bash -vagrant up -vagrant ssh-config > vagrant-ssh -ssh -F vagrant-ssh default -``` - -## Launching jupyter-forward - -```bash -jupyter-forward vagrant@127.0.0.1:2222 --identity ./.vagrant/machines/default/virtualbox/private_key -``` diff --git a/docs/source/explanation/index.md b/docs/source/explanation/index.md new file mode 100644 index 0000000..b1303b4 --- /dev/null +++ b/docs/source/explanation/index.md @@ -0,0 +1 @@ +# Explanation diff --git a/docs/source/how-to/index.md b/docs/source/how-to/index.md new file mode 100644 index 0000000..6de89d0 --- /dev/null +++ b/docs/source/how-to/index.md @@ -0,0 +1,10 @@ +# How to + +How to: + +```{toctree} +--- +maxdepth: 1 +--- +install-jupyter-forward.md +``` diff --git a/docs/source/how-to/install-jupyter-forward.md b/docs/source/how-to/install-jupyter-forward.md new file mode 100644 index 0000000..07e3efb --- /dev/null +++ b/docs/source/how-to/install-jupyter-forward.md @@ -0,0 +1,33 @@ +# Install jupyter-forward + +jupyter-forward can be installed in three ways: + +```{eval-rst} +.. tab:: pip + + Using the `pip `__ package manager: + + .. code:: bash + + $ python -m pip install jupyter-forward + +.. tab:: conda + + Using the `conda `__ package manager that comes with the + Anaconda/Miniconda distribution: + + .. code:: bash + + $ conda install jupyter-forward --channel conda-forge + +.. tab:: Development version + + To install a development version from source: + + .. code:: bash + + $ git clone https://github.com/NCAR/jupyter-forward + $ cd jupyter-forward + $ python -m pip install -e . + +``` diff --git a/docs/source/index.md b/docs/source/index.md index 57ef753..bd41052 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -1,27 +1,40 @@ -```{include} ../../README.md +# Welcome to jupyter-forward's documentation! -``` +Jupyter-forward simplifies the process of running `jupyter lab` on a remote machine by performing the following tasks on behalf of the users: -## Feedback +1. Logging into a remote cluster/resource via the SSH protocol. +2. Launching Jupyter Lab on the remote cluster. +3. Port forwarding Jupyter Lab session back to your local machine. +4. Opening the port forwarded Jupyter Lab session in your local browser. -If you encounter any errors or problems with **jupyter-forward**, please open an issue at the GitHub [main repository](http://github.com/NCAR/jupyter-forward). +## Get in touch -## Documentation Contents +- If you encounter any errors or problems with **jupyter-forward**, please open an issue at the GitHub [main repository](http://github.com/NCAR/jupyter-forward/issues). +- If you have a question like "How do I find x?", ask on [GitHub discussions](https://github.com/NCAR/jupyter-forward/discussions). Please include a self-contained reproducible example if possible. ```{toctree} --- -maxdepth: 2 -caption: Using jupyter-forward +maxdepth: 1 +hidden: --- -installation.md -usage.md -examples.md + +tutorials/index.md +how-to/index.md +explanation/index.md +reference/index.md + ``` ```{toctree} --- maxdepth: 2 -caption: Reference +caption: Contribute to jupyter-forward +hidden: --- + +contributing.md changelog.md +GitHub Repo +GitHub discussions + ``` diff --git a/docs/source/installation.md b/docs/source/installation.md deleted file mode 100644 index 448798c..0000000 --- a/docs/source/installation.md +++ /dev/null @@ -1,13 +0,0 @@ -# Installation - -Jupyter-forward can be installed from PyPI with pip: - -```bash -python -m pip install jupyter-forward -``` - -Jupyter-forward is also available from conda-forge for conda installations: - -```bash -conda install -c conda-forge jupyter-forward -``` diff --git a/docs/source/usage.md b/docs/source/reference/index.md similarity index 100% rename from docs/source/usage.md rename to docs/source/reference/index.md diff --git a/docs/source/examples.md b/docs/source/tutorials/index.md similarity index 99% rename from docs/source/examples.md rename to docs/source/tutorials/index.md index c2cb005..9e9d696 100644 --- a/docs/source/examples.md +++ b/docs/source/tutorials/index.md @@ -1,4 +1,4 @@ -# Examples +# Tutorial ## Launching Jupyter Lab on a Remote Host's Login Node diff --git a/readthedocs.yml b/readthedocs.yml index 1abfbb5..89f13eb 100644 --- a/readthedocs.yml +++ b/readthedocs.yml @@ -1,5 +1,7 @@ +version: 2 conda: - file: docs/environment.yml -python: - version: 3.8 - setup_py_install: true + environment: docs/environment.yml +build: + os: 'ubuntu-20.04' + tools: + python: 'mambaforge-4.10'