Merge pull request #51 from bollwyvl/gh-50-pre-docs

Update docs for 0.4.0 release

Author: bollwyvl

CONTRIBUTING.md

@@ -2,12 +2,12 @@
 
 ## Get `CONDA_EXE`
 
-- Get [miniforge](https://github.com/conda-forge/miniforge)
+- Get [Mambaforge](https://conda-forge.org/miniforge/)
 
 ```bash
-conda install -c conda-forge doit
- optional meta-dependencies
-conda install -c conda-forge conda-lock mamba
+mamba install -c conda-forge doit
+# optional meta-dependency
+mamba install -c conda-forge conda-lock
 ```
 
 ## Get the code
@@ -51,36 +51,45 @@ 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:
+For example, if `linux-64` running `python3.7` with `jupyterlab 1` failed:
 
 ```bash
 !/usr/bin/env bash
 set -eux
-RFJL_LOCKDIR=test/linux-64/py3.6/lab1 doit release
+RFJL_LOCKDIR=test/linux-64/py3.7/lab1 doit release
 ```
 
 Or, in a `bat` script:
 
 ```bat
 @echo on
-set RFJL_LOCKDIR=test/win-64/py3.9/lab1
+set RFJL_LOCKDIR=test/win-64/py3.7/lab1
 doit release
 ```
 
 This will recreate the `test` environment with the specified lockfile, and
 repeat all the steps.
 
-### Releasing
-
-- ensure `VERSION` has been increased appropriately
-- ensure `HISTORY.ipynb` is up-to-date
-- (usually) grab the `dist` assets from CI, unpack into `./dist`
-- make a GitHub release, adding the `.tar.gz`, `.whl`, and `SHA256SUMS`
-- upload to PyPI
-
+## Releasing
+
+- [ ] merge all outstanding PRs
+- [ ] start a release issue with a checklist (maybe like this one)
+- [ ] ensure `VERSION` has been increased appropriately
+- [ ] ensure the `HISTORY.ipynb` is up-to-date
+- [ ] validate on binder
+- [ ] validate on ReadTheDocs
+- [ ] wait for a successful build of `master`
+- [ ] download the `dist` archive and unpack somewhere (maybe a fresh `dist`)
+- [ ] create a new release through the GitHub UI
+  - [ ] paste in the relevant `HISTORY` entries
+  - [ ] upload the artifacts
+- [ ] actually upload to pypi.org
   ```bash
   doit publish
   ```
-
-- do a post-mortem issue
-- bump `VERSION` to a working status
+- [ ] postmortem
+  - [ ] handle `conda-forge` feedstock tasks
+  - [ ] validate on binder via simplest-possible gists
+  - [ ] activate the version on ReadTheDocs
+  - [ ] bump `VERSION` to next development version
+  - [ ] update release procedures

_scripts/project.py

@@ -104,7 +104,7 @@
 DOCS = ROOT / "docs"
 RTD_ENV = DOCS / "rtd.yml"
 DOCS_CONF_PY = DOCS / "conf.py"
-DOCS_BUILDINFO = BUILD / "docs" / "html" / ".buildinfo"
+DOCS_BUILDINFO = BUILD / "docs/html/.buildinfo"
 
 # demo
 LABEXTXT = BINDER / "labex.txt"
@@ -239,6 +239,8 @@ def _is_excluded(flow, pf, py, lab):
         DOCS_CONF_PY,
     ]
     if ".ipynb_checkpoints" not in str(p)
+    and "_robot_magic_" not in str(p)
+    and not p.name.endswith(".html")
 ]
 
 PACKAGE_JSON = ROOT / "package.json"

docs/CI.ipynb

@@ -99,7 +99,7 @@
     ">\n",
     "> A small collection of [scripts][], not shipped as part of the distribution, provide some custom behaviors around particularly complex tasks.\n",
     "> \n",
-    "> - sometimes `doit` is to heavy of a hammer for delicate work\n",
+    "> - sometimes `doit` is too heavy of a hammer for delicate work\n",
     "\n",
     "[scripts]: https://github.com/robots-from-jupyter/robotframework-jupyterlibrary/tree/master/scripts\n",
     "[doit]: https://github.com/robots-from-jupyter/robotframework-jupyterlibrary/blob/master/dodo.py"
@@ -124,15 +124,15 @@
     "A heavy CI pipeline can become necessary to manage many competing concerns. Each non-trivial, browser-based robot test can easily cost tens of seconds. Some approaches:\n",
     "- use an up-front dry-run `robot` test\n",
     "  - this can help catch whitespace errors in robot syntax\n",
-    "  - this usually costs $\\frac{\\sim1}{100}$ the time of running the full test \n",
-    "- run tests in subsets and in parallel with `pabot`\n",
+    "  - this usually costs $\\frac{\\sim1}{100}$ the time of running the full test\n",
+    "- run tests in subsets, in parallel, and in random order with `pabot`\n",
     "  - requires avoiding shared resources, e.g. network ports, databases, logfiles"
    ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -146,7 +146,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.0"
+   "version": "3.8.12"
   }
  },
  "nbformat": 4,

docs/INSTALL.ipynb

@@ -38,14 +38,17 @@
     "Here's a complete setup:\n",
     "```shell\n",
     "conda create --name testing-jupyter --channel conda-forge \n",
-    "  python=3 \\   # 3.6 required, not tested with pypy  \n",
+    "  python=3 \\   # 3.7 required, not tested with pypy  \n",
     "  jupyterlab \\\n",
     "  robotframework-seleniumlibrary \\\n",
-    "  geckodriver\n",
+    "  geckodriver \\\n",
+    "  firefox\n",
     "\n",
     "conda activate testing-jupyter\n",
     "\n",
-    "pip install --no-deps \\             # don't want any surprises\n",
+    "pip install \\\n",
+    "  --no-deps \\             # don't want any surprises\n",
+    "  --ignore-installed \\    # just to be sure\n",
     "  git+http://github.com/robots-from-jupyter/robotframework-jupyterlibrary\n",
     "```"
    ]
@@ -79,13 +82,13 @@
    },
    "outputs": [],
    "source": [
-    "!python ../dodo.py list --all --status"
+    "!python ../dodo.py list --all"
    ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -99,7 +102,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.2"
+   "version": "3.8.12"
   },
   "nteract": {
    "version": "nteract-on-jupyter@0.35.4"

docs/KEYWORDS.ipynb

@@ -144,7 +144,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -158,7 +158,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.2"
+   "version": "3.8.12"
   }
  },
  "nbformat": 4,

docs/LIMITS.ipynb

@@ -32,7 +32,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -46,7 +46,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.2"
+   "version": "3.8.12"
   }
  },
  "nbformat": 4,

docs/MAGIC.ipynb

@@ -173,7 +173,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -187,7 +187,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.2"
+   "version": "3.8.12"
   }
  },
  "nbformat": 4,

docs/WHY.ipynb

@@ -31,21 +31,23 @@
    "source": [
     "## ...JupyterLibrary?\n",
     "\n",
-    "Powered by [Robot Framework](https://robotframework.org), `JupyterLibrary` allows you to:\n",
+    "Powered by [Robot Framework](https://robotframework.org) and [SeleniumLibrary](https://robotframework.org/SeleniumLibrary/SeleniumLibrary.html), `JupyterLibrary` allows you to:\n",
     "\n",
-    "- write tests in concise, plain language\n",
+    "- write tests in concise, **plain language**\n",
     "  - and extend this language to meet your needs\n",
-    "- run in multiple browsers (even at the same time)\n",
-    "  - run on multiple operating systems\n",
-    "- view rich reports of your test results\n",
-    "  - but also compare your reports over time with machine-readable formats\n",
-    "- generate screenshots to augment your documentation"
+    "- test multiple Jupyter **clients**\n",
+    "  - and multiple **versions** of them\n",
+    "- run in multiple, **real browsers** (even at the same time)\n",
+    "  - and on multiple **operating systems**\n",
+    "- view rich **reports** of your test results\n",
+    "  - but also compare your reports over time with **machine-readable** formats\n",
+    "- generate **screenshots** to augment your documentation"
    ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -59,7 +61,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.2"
+   "version": "3.8.12"
   }
  },
  "nbformat": 4,

docs/conf.py

@@ -20,6 +20,8 @@
 
 CONF = {k: _parser[k] for k in _parser.sections()}
 YEAR = datetime.now().year
+KEYWORDS = "*** Keywords ***"
+VARIABLES = "*** Variables ***"
 
 
 def setup(app):
@@ -38,12 +40,26 @@ def setup(app):
 
     for client_dir in CLIENTS:
         client = Path(client_dir)
+        print(client.name)
         with TemporaryDirectory() as td:
             tdp = Path(td)
-            agg = ""
+            agg = "\n".join(
+                [
+                    "*** Settings ***",
+                    f"Documentation    Keywords for {client.name}",
+                    "",
+                ]
+            )
             for sub in sorted(client.rglob("*.resource")):
-                print(f"collecting {sub.relative_to(client)}")
-                agg += sub.read_text()
+                sub_text = sub.read_text()
+                has_vars = VARIABLES in sub_text
+                has_kw = KEYWORDS in sub_text
+                print(f"... collecting {sub.relative_to(client)}")
+                print(f"    ... keywords?  {has_kw}")
+                print(f"    ... variables? {has_vars}")
+
+                split_on = VARIABLES if has_vars else KEYWORDS
+                agg += "\n".join([split_on, sub_text.split(split_on)[1], ""])
             out_file = Path(tdp / f"{client.name}.resource")
             out_file.write_text(agg)
             subprocess.run(

docs/index.ipynb

@@ -31,7 +31,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -45,7 +45,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.2"
+   "version": "3.8.12"
   }
  },
  "nbformat": 4,