diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 151d82be..5f658f10 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,21 +1,69 @@ -# Contributing to JupyterLibrary +## Contributing to JupyterLibrary -## [Environment](#Environment) - -Get `$CONDA_EXE`: +### Get `CONDA_EXE` - Get [miniforge](https://github.com/conda-forge/miniforge) ```bash conda install -c conda-forge doit +# optional meta-dependencies +conda install -c conda-forge conda-lock mamba ``` -- optionally install - - `mamba` for faster solves - - `conda-lock` if changing dependencies +### Get the code + +```bash +git clone http://github.com/robots-from-jupyter/robotframework-jupyterlibrary +cd robotframework-jupyterlibrary +``` -## Doit +### Doit + +#### Listing all the tasks + +```shell +doit list +``` + +#### Just run (just about) everything ```shell doit release ``` + +#### Lock Files + +> After adding/changing any dependencies in `.github/env_specs`, the _lockfiles_ +> need to be refreshed in `.github/locks` and committed. +> +> Requires `conda-lock`, and optionally `mamba` for faster solves + +```shell +doit lock +``` + +#### Reproducing CI failures + +By default, the `doit` scripts use the lockfile most like where you are +developing, hoping for a better cache hit rate. On the same _operating system_, +however, any of the pre-solved lockfiles can be used, by specifying the +`RJFL_LOCKFILE` environment variable. + +For example, if `linux-64` running `python3.6` with `jupyterlab 1` failed: + +```bash +#!/usr/bin/env bash +set -eux +RFJL_LOCKDIR=test/linux-64/py3.6/lab1 doit release +``` + +Or, in a `bat` script: + +```bat +@echo on +set RFJL_LOCKDIR=test/win-64/py3.9/lab1 +doit release +``` + +This will recreate the `test` environment with the specified lockfile, and +repeat all the steps. diff --git a/README.md b/README.md index bae770c6..c8d6329c 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,8 @@ # Using -Write `.robot` files that use `JupyterLibrary` keywords. +Write `.robot` files that use `JupyterLibrary` [keywords][]... or use [magics][] +in notebooks. ```robotframework *** Settings *** @@ -30,8 +31,6 @@ A Notebook in JupyterLab Capture Page Screenshot ``` -> or use [magics][] in notebooks. - See the [acceptance tests][] for examples. # Installation @@ -46,28 +45,7 @@ Or conda install -c conda-forge robotframework-jupyterlibrary ``` -## Development Installation - -- get Firefox - - Chrome works, too, but more fickle -- get [Miniforge][] (as in Python 3.6+) -- clone this repo... - - git clone https://github.com/robots-from-jupyter/robotframework-jupyterlibrary - cd robotframework-jupyterlibrary - -- update and activate... - - conda env update - conda activate robotframework-jupyterlibrary - -- then... - - pip install -e . --no-deps --ignore-installed - -- run the tests... - - python -m scripts.atest +Or see the [contributing guide][contributing] for a development install. # Free Software @@ -98,10 +76,11 @@ contains code from a number of other projects: [conda-forge-badge]: https://img.shields.io/conda/vn/conda-forge/robotframework-jupyterlibrary.svg [docs]: https://robotframework-jupyterlibrary.readthedocs.io -[seleniumlibrary]: https://github.com/robotframework/SeleniumLibrary -[selibrary-license]: - https://github.com/robotframework/SeleniumLibrary/blob/master/LICENSE.txt [jyve]: https://github.com/deathbeds/jyve [jyve-license]: https://github.com/deathbeds/jyve/blob/master/LICENSE [magics]: https://robotframework-jupyterlibrary.readthedocs.io/en/stable/MAGIC.html +[keywords]: + https://robotframework-jupyterlibrary.readthedocs.io/en/stable/KEYWORDS.html +[contributing]: + https://github.com/robots-from-jupyter/robotframework-jupyterlibrary/blob/master/CONTRIBUTING.md diff --git a/docs/INSTALL.ipynb b/docs/INSTALL.ipynb index 76e6a9c8..09f891b8 100644 --- a/docs/INSTALL.ipynb +++ b/docs/INSTALL.ipynb @@ -37,84 +37,46 @@ "\n", "Here's a complete setup:\n", "```shell\n", - "conda create \\\n", - " -n testing-jupyter \\ # as good a name as any\n", - " python=3 # 2020 is right around the corner\n", + "conda create --name testing-jupyter --channel conda-forge \n", + " python=3 \\ # 3.6 required, not tested with pypy \n", + " jupyterlab \\\n", + " robotframework-seleniumlibrary \\\n", + " geckodriver\n", "\n", - "conda activate testing-jupyter # get on the right PATH\n", - "\n", - "conda install \\\n", - " -c conda-forge \\ # can't get all these from Austin\n", - " jupyterlab \\ # mostly this\n", - " robotframework-seleniumlibrary \\ # includes robotframework... and selenium\n", - " geckodriver \\ # moz:\\\\a FTW\n", - " python-chromedriver-binary # for the rest of the marketshare\n", + "conda activate testing-jupyter\n", "\n", "pip install --no-deps \\ # don't want any surprises\n", - " git+http://github.com/robots-from-jupyter/robotframework-jupyterlibrary#egg=JupyterLibrary\n", + " git+http://github.com/robots-from-jupyter/robotframework-jupyterlibrary\n", "```" ] }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "jupyter": { + "source_hidden": true + } + }, + "outputs": [], + "source": [ + "__import__(\"IPython\").display.Markdown(\"../CONTRIBUTING.md\")" + ] + }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## DEV\n", - "- clone\n", - " \n", - "```bash\n", - "git clone http://github.com/robots-from-jupyter/robotframework-jupyterlibrary\n", - "cd robotframework-jupyterlibrary\n", - "```\n", - "\n", - "- update and activate\n", - "\n", - "```bash\n", - "conda install -c conda-forge doit\n", - "```\n", - "\n", - "- then\n", - "\n", - "```bash\n", - "doit list\n", - "```\n", - "\n", - "- a good starting point is everything needed to cut the next release\n", - "\n", - "```bash\n", - "doit release\n", - "```\n", - "\n", - "- a special case: if you want to update package versions, add new CI excursions, get `conda-lock` with `pip`, `conda` or `mamba`, then:\n", - "\n", - "```bash\n", - "doit lock\n", - "```" + "### Appendix: Current tasks" ] }, { - "cell_type": "markdown", + "cell_type": "code", + "execution_count": null, "metadata": {}, + "outputs": [], "source": [ - "### Reproducing CI failures\n", - "\n", - "By default, the `doit` scripts use the lockfile most like where you are developing, hoping for a better cache hit rate. On the same _operating system_, however, any of the pre-solved lockfiles can be used, by specifying the `RJFL_LOCKFILE` environment variable.\n", - "\n", - "For example, if `linux-64` running `python3.6` with `jupyterlab 1` failed:\n", - "```bash\n", - "#!/usr/bin/env bash\n", - "set -eux\n", - "RFJL_LOCKDIR=test/linux-64/py3.6/lab1 doit release\n", - "```\n", - "\n", - "Or, in a `bat` script:\n", - "```bat\n", - "@echo on\n", - "set RFJL_LOCKFILE=test/win-64/py3.9/lab1 \n", - "doit release\n", - "```\n", - "\n", - "This will recreate the `test` environment with the specified lockfile, and repeat all the steps." + "!python ../dodo.py list --all --status" ] } ], diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css index 1c47d40b..8b008dd5 100644 --- a/docs/_static/css/custom.css +++ b/docs/_static/css/custom.css @@ -96,6 +96,16 @@ a:active { background-color: transparent; } +body div.nbinput.container div[class*='highlight'], +body div.nboutput.container div[class*='highlight'] { + background-color: black; + padding: 0.25em; +} + +body div.nboutput.container div[class*='highlight'] { + margin-bottom: 1em; +} + div.nbinput div.prompt, div.nboutput div.prompt { display: none; diff --git a/docs/conf.py b/docs/conf.py index d5485d0d..41266c6b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -149,7 +149,7 @@ def setup(app): exclude_patterns = [".ipynb_checkpoints", "**/.ipynb_checkpoints"] # The name of the Pygments (syntax highlighting) style to use. -pygments_style = None +pygments_style = "native" # -- Options for HTML output ------------------------------------------------- diff --git a/dodo.py b/dodo.py index 9d1b9e66..931a8ba9 100644 --- a/dodo.py +++ b/dodo.py @@ -215,6 +215,7 @@ def task_lint(): def task_js(): + """javascript cruft""" env = "lint" run_in = P.RUN_IN[env] @@ -305,11 +306,14 @@ def _make_setup(env): P.DIST, P.SETUP["metadata"]["name"], ] + doc = f"[{env}] install from dist" else: pip_args = ["-e", "."] + doc = f"[{env}] python development install" yield dict( name=env, + doc=doc, actions=[ lambda: frozen.unlink() if frozen.exists() else None, [*pym, "pip", "install", "--no-deps", "--ignore-installed", *pip_args], @@ -359,6 +363,7 @@ def task_test(): yield dict( name="atest", + doc="run acceptance tests with robot", uptodate=[config_changed(os.environ.get("ATEST_ARGS", ""))], actions=[clean, [*pym, "_scripts.atest"], touch], file_dep=[P.OK.robot_dry_run, *robot_deps], @@ -368,6 +373,7 @@ def task_test(): # Presently not running this on CI yield dict( name="combine", + doc="combine all robot outputs into a single HTML report", actions=[[*pym, "_scripts.combine"]], file_dep=[ real_target, diff --git a/setup.cfg b/setup.cfg index 4d0d8a49..a65e9b6c 100644 --- a/setup.cfg +++ b/setup.cfg @@ -12,7 +12,7 @@ project_urls = CI = https://github.com/robots-from-jupyter/robotframework-jupyterlibrary/actions Documentation = https://robotframework-jupyterlibrary.readthedocs.io/en/stable Releases = https://github.com/robots-from-jupyter/robotframework-jupyterlibrary/releases - Source Code = https://gitlab.com/robots-from-jupyter/robotframework-jupyterlibrary + Source Code = https://github.com/robots-from-jupyter/robotframework-jupyterlibrary author = Robots from Jupyter author_email = nick.bollweg@gmail.com license = BSD-3-Clause diff --git a/src/JupyterLibrary/VERSION b/src/JupyterLibrary/VERSION index c181bf59..0d91a54c 100644 --- a/src/JupyterLibrary/VERSION +++ b/src/JupyterLibrary/VERSION @@ -1 +1 @@ -0.3.0a0 +0.3.0