Release v0.3.0 (#25)

Author: bollwyvl

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.

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

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"
    ]
   }
  ],

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;

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

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,

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 = [email protected]
 license = BSD-3-Clause

src/JupyterLibrary/VERSION

@@ -1 +1 @@
-0.3.0a0
+0.3.0