Rearrange docs + Use furo theme

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 <https://pre-commit.com>`\_ 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 "<commit message>"
+   $ 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
+````
+
+```
+
+```

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

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 ..

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 <a href="https://ebp.jupyterbook.org">Executable Book Project</a>""",
-)
+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)}

docs/source/contributing.md

@@ -0,0 +1,3 @@
+```{include} ../../CONTRIBUTING.md
+
+```