diff --git a/.eslintignore b/.eslintignore index dc8fffe..4cb87e8 100644 --- a/.eslintignore +++ b/.eslintignore @@ -1,4 +1,5 @@ node_modules dist +docs coverage **/*.d.ts \ No newline at end of file diff --git a/.prettierignore b/.prettierignore index 79c7b6a..07b724b 100644 --- a/.prettierignore +++ b/.prettierignore @@ -3,3 +3,4 @@ node_modules **/lib **/package.json ipylab/labextension +docs diff --git a/README.md b/README.md index 5179bf0..7bbd32c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # ipylab ![Github Actions Status](https://github.com/jtpio/ipylab/workflows/Build/badge.svg) +[![JupyterLite](https://jupyterlite.rtfd.io/en/latest/_static/badge-launch.svg)](https://ipylab.readthedocs.io/en/latest/lite/lab) [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jtpio/ipylab/main?urlpath=lab/tree/examples/widgets.ipynb) [![Conda Version](https://img.shields.io/conda/vn/conda-forge/ipylab.svg)](https://anaconda.org/conda-forge/ipylab) [![pypi](https://img.shields.io/pypi/v/ipylab.svg)](https://pypi.python.org/pypi/ipylab) @@ -22,6 +23,10 @@ Try it in your browser with Binder: [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jtpio/ipylab/main?urlpath=lab/tree/examples/widgets.ipynb) +Or with [JupyterLite](https://github.com/jupyterlite/jupyterlite): + +[![JupyterLite](https://jupyterlite.rtfd.io/en/latest/_static/badge-launch.svg)](https://ipylab.readthedocs.io/en/latest/lite/lab) + ## Examples ### Add Jupyter Widgets to the JupyterLab interface diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..53436ef --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,21 @@ +extensions = ["myst_parser", "jupyterlite_sphinx"] + +jupyterlite_config = "jupyter_lite_config.json" +jupyterlite_dir = "." +jupyterlite_contents = "../examples" + +master_doc = "index" +source_suffix = ".md" + +# General information about the project. +project = "ipylab" +author = "ipylab contributors" + +exclude_patterns = [] +highlight_language = "python" +pygments_style = "sphinx" + +html_theme = "pydata_sphinx_theme" +html_static_path = ["_static"] + +html_css_files = ["custom.css"] diff --git a/docs/environment.yml b/docs/environment.yml index fe685e0..0476ae5 100644 --- a/docs/environment.yml +++ b/docs/environment.yml @@ -1,11 +1,17 @@ - -name: ipylab_docs +name: ipylab-lite channels: - - conda-forge +- conda-forge dependencies: -- python=3.9 -- nodejs -- numpy -- sphinx -- nbsphinx -- jupyter_sphinx +- build +- python=3.11 +- mamba +- pydata-sphinx-theme +- myst-parser +- ipywidgets>=8.0,<9 +- jupyterlab>=3.5.0,<4 +- nodejs=18 +- pip: + - jupyterlite-sphinx + - jupyterlite-core==0.1.0b22 + - jupyterlite-pyodide-kernel==0.0.5 + - .. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..451beda --- /dev/null +++ b/docs/index.md @@ -0,0 +1,2 @@ +```{include} ../README.md +``` diff --git a/docs/jupyter_lite_config.json b/docs/jupyter_lite_config.json new file mode 100644 index 0000000..ccaeda7 --- /dev/null +++ b/docs/jupyter_lite_config.json @@ -0,0 +1,8 @@ +{ + "PipliteAddon": { + "piplite_urls": [ + "../dist", + "https://files.pythonhosted.org/packages/py3/i/ipywidgets/ipywidgets-8.0.4-py3-none-any.whl" + ] + } +} diff --git a/docs/source/_static/helper.js b/docs/source/_static/helper.js deleted file mode 100644 index cb2e2a8..0000000 --- a/docs/source/_static/helper.js +++ /dev/null @@ -1,5 +0,0 @@ -var cache_require = window.require; - -window.addEventListener('load', function() { - window.require = cache_require; -}); diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 6166198..0000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,194 +0,0 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- -# -# ipylab documentation build configuration file -# -# 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. - - -# -- 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", - "sphinx.ext.intersphinx", - "sphinx.ext.napoleon", - "sphinx.ext.todo", - "nbsphinx", -] - -# Ensure our extension is available: -import json -import sys -from os.path import dirname, join as pjoin - -docs = dirname(dirname(__file__)) -root = dirname(docs) -sys.path.insert(0, root) -sys.path.insert(0, pjoin(docs, "sphinxext")) - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = ".rst" - -# The master toctree document. -master_doc = "index" - -# General information about the project. -project = "ipylab" -copyright = "2019, ipylab contributors" -author = "ipylab contributors" - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. - - -# get version from python package: -import os - -here = os.path.dirname(__file__) -repo = os.path.join(here, "..", "..") -with open(os.path.join(repo, "package.json")) as f: - package = json.load(f) - _version_js = package["version"] - -# The short X.Y version. -version = "%i.%i" % tuple(int(part) for part in _version_js.split("."))[:2] -# The full version, including alpha/beta/rc tags. -release = ( - _version_js.replace("-alpha.", "a").replace("-beta.", "b").replace("-rc.", "rc") -) - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# 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 - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ["**.ipynb_checkpoints"] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = "sphinx" - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False - - -# -- Options for HTML output ---------------------------------------------- - - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# 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"] - - -# -- Options for HTMLHelp output ------------------------------------------ - -# Output file base name for HTML help builder. -htmlhelp_basename = "ipylabdoc" - - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, "ipylab.tex", "ipylab Documentation", "ipylab contributors", "manual"), -] - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [(master_doc, "ipylab", "ipylab Documentation", [author], 1)] - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ( - master_doc, - "ipylab", - "ipylab Documentation", - author, - "ipylab", - "Python bridge to JupyterLab", - "Miscellaneous", - ), -] - - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {"https://docs.python.org/": None} - -# Read The Docs -# on_rtd is whether we are on readthedocs.org, this line of code grabbed from -# docs.readthedocs.org -on_rtd = os.environ.get("READTHEDOCS", None) == "True" - -if not on_rtd: # only import and set the theme if we're building docs locally - import sphinx_rtd_theme - - html_theme = "sphinx_rtd_theme" - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - -# otherwise, readthedocs.org uses their theme by default, so no need to specify it - - -# Uncomment this line if you have know exceptions in your included notebooks -# that nbsphinx complains about: -# -nbsphinx_allow_errors = True # exception ipstruct.py ipython_genutils diff --git a/docs/source/develop-install.rst b/docs/source/develop-install.rst deleted file mode 100644 index 5e271d1..0000000 --- a/docs/source/develop-install.rst +++ /dev/null @@ -1,31 +0,0 @@ - -Developer install -================= - - -To install a developer version of ipylab, you will first need to clone -the repository:: - - git clone https://github.com//ipylab - cd ipylab - -Next, install it with a develop install using pip:: - - pip install -e . - - -If you are planning on working on the JS/frontend code, you should also do -a link installation of the extension:: - - jupyter nbextension install [--sys-prefix / --user / --system] --symlink --py ipylab - - jupyter nbextension enable [--sys-prefix / --user / --system] --py ipylab - -with the `appropriate flag`_. Or, if you are using Jupyterlab:: - - jupyter labextension install . - - -.. links - -.. _`appropriate flag`: https://jupyter-notebook.readthedocs.io/en/stable/extending/frontend_extensions.html#installing-and-enabling-extensions diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst deleted file mode 100644 index 26b2bd2..0000000 --- a/docs/source/examples/index.rst +++ /dev/null @@ -1,18 +0,0 @@ - -Examples -======== - -This section contains several examples generated from Jupyter notebooks. -The widgets have been embedded into the page for demonstrative pruposes. - -.. todo:: - - Add links to notebooks in examples folder similar to the initial - one. This is a manual step to ensure only those examples that - are suited for inclusion are used. - - -.. toctree:: - :glob: - - * diff --git a/docs/source/examples/introduction.nblink b/docs/source/examples/introduction.nblink deleted file mode 100644 index 258bb0f..0000000 --- a/docs/source/examples/introduction.nblink +++ /dev/null @@ -1,3 +0,0 @@ -{ - "path": "../../../examples/introduction.ipynb" -} diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 704f4f6..0000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,49 +0,0 @@ - -ipylab -===================================== - -Version: |release| - -Python bridge to JupyterLab - - -Quickstart ----------- - -To get started with ipylab, install with pip:: - - pip install ipylab - -or with conda:: - - conda install ipylab - - -Contents --------- - -.. toctree:: - :maxdepth: 2 - :caption: Installation and usage - - installing - introduction - -.. toctree:: - :maxdepth: 1 - - examples/index - - -.. toctree:: - :maxdepth: 2 - :caption: Development - - develop-install - - -.. links - -.. _`Jupyter widgets`: https://jupyter.org/widgets.html - -.. _`notebook`: https://jupyter-notebook.readthedocs.io/en/latest/ diff --git a/docs/source/installing.rst b/docs/source/installing.rst deleted file mode 100644 index 0ed1102..0000000 --- a/docs/source/installing.rst +++ /dev/null @@ -1,37 +0,0 @@ - -.. _installation: - -Installation -============ - - -The simplest way to install ipylab is via pip:: - - pip install ipylab - -or via conda:: - - conda install ipylab - - -If you installed via pip, and notebook version < 5.3, you will also have to -install / configure the front-end extension as well. If you are using classic -notebook (as opposed to Jupyterlab), run:: - - jupyter nbextension install [--sys-prefix / --user / --system] --py ipylab - - jupyter nbextension enable [--sys-prefix / --user / --system] --py ipylab - -with the `appropriate flag`_. If you are using Jupyterlab, install the extension -with:: - - jupyter labextension install ipylab - -If you are installing using conda, these commands should be unnecessary, but If -you need to run them the commands should be the same (just make sure you choose the -`--sys-prefix` flag). - - -.. links - -.. _`appropriate flag`: https://jupyter-notebook.readthedocs.io/en/stable/extending/frontend_extensions.html#installing-and-enabling-extensions diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst deleted file mode 100644 index ad0edd4..0000000 --- a/docs/source/introduction.rst +++ /dev/null @@ -1,7 +0,0 @@ -============= -Introduction -============= - -.. todo:: - - add prose explaining project purpose and usage here diff --git a/examples/commands.ipynb b/examples/commands.ipynb index 787ead2..9ac8668 100644 --- a/examples/commands.ipynb +++ b/examples/commands.ipynb @@ -7,6 +7,15 @@ "# Command Registry" ] }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "%pip install -q ipylab" + ] + }, { "cell_type": "code", "execution_count": null, diff --git a/examples/icons.ipynb b/examples/icons.ipynb index fd68652..d8ca5f0 100644 --- a/examples/icons.ipynb +++ b/examples/icons.ipynb @@ -16,6 +16,16 @@ "Icons can be applied to both the `Title` of a `Panel` [widgets](./widgets.ipynb) and [commands](./commands.ipynb), providing more customization than `icon_class`." ] }, + { + "cell_type": "code", + "execution_count": null, + "id": "5eb2e5cc", + "metadata": {}, + "outputs": [], + "source": [ + "%pip install -q ipylab" + ] + }, { "cell_type": "code", "execution_count": null, diff --git a/examples/ipytree.ipynb b/examples/ipytree.ipynb index cad8669..d144571 100644 --- a/examples/ipytree.ipynb +++ b/examples/ipytree.ipynb @@ -13,6 +13,15 @@ "First let's define some imports." ] }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "%pip install -q ipylab" + ] + }, { "cell_type": "code", "execution_count": null, diff --git a/examples/sessions.ipynb b/examples/sessions.ipynb index 7f29078..23437dc 100644 --- a/examples/sessions.ipynb +++ b/examples/sessions.ipynb @@ -7,6 +7,15 @@ "# Session Manager" ] }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "%pip install -q ipylab" + ] + }, { "cell_type": "code", "execution_count": null, diff --git a/examples/widgets.ipynb b/examples/widgets.ipynb index 8318d20..d6cecbf 100644 --- a/examples/widgets.ipynb +++ b/examples/widgets.ipynb @@ -7,6 +7,15 @@ "# Panels and Widgets" ] }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "%pip install -q ipylab" + ] + }, { "cell_type": "code", "execution_count": null, diff --git a/readthedocs.yml b/readthedocs.yml index ba61a33..a7c84ab 100644 --- a/readthedocs.yml +++ b/readthedocs.yml @@ -3,6 +3,11 @@ build: os: ubuntu-20.04 tools: python: mambaforge-4.10 + jobs: + pre_build: + - jlpm + - jlpm build + - python -m build --wheel python: install: - method: pip