more docs hacking

bollwyvl · bollwyvl · commit bd2cf835188e · 2018-12-11T00:00:01.000-05:00
diff --git a/.readthedocs.yml b/.readthedocs.yml
diff --git a/anaconda-project.yml b/anaconda-project.yml
@@ -78,7 +78,6 @@ env_specs:
     - nodejs
     - pillow
     - python-chromedriver-binary
-    - recommonmark
     - robotframework >=3.1
     - robotframework-lint
     - robotframework-seleniumlibrary >=3.2
diff --git a/atest/acceptance/01_server/00_basic.robot b/atest/acceptance/01_server/00_basic.robot
@@ -29,7 +29,7 @@ Start three servers
     ${terminated} =    Terminate All Jupyter Servers
     Should be equal as integers    ${terminated}    0    msg=No servers should have been terminated
 
-Notebook Files
+Server Files
     [Setup]    Create File    ${OUTPUT_DIR}${/}foo.txt    bar
     ${nb1} =    Start New Jupyter Server    stdout=${OUTPUT_DIR}${/}files.log    stderr=STDOUT
     Copy Files to Jupyter Directory    ${OUTPUT_DIR}${/}*.txt
diff --git a/atest/acceptance/10_lab/10_notebook.robot b/atest/acceptance/10_lab/10_notebook.robot
@@ -17,6 +17,6 @@ IPython Notebook Outputs
     Open JupyterLab
     Launch a new JupyterLab Document
     : FOR    ${i}    IN RANGE    ${10}
-    \    Add and Run Cell    print("${i} hello world " * ${i ** 2})
+    \    Add and Run JupyterLab Code Cell    print("${i} hello world " * ${i ** 2})
     Wait Until JupyterLab Kernel Is Idle
     Screenshot Each Output of Active JupyterLab Document    ipython_outputs${/}
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -12,7 +12,6 @@
 from tempfile import TemporaryDirectory
 
 import nbsphinx
-from recommonmark.parser import CommonMarkParser
 
 
 nbsphinx.RST_TEMPLATE = nbsphinx.RST_TEMPLATE.replace(
@@ -73,10 +72,7 @@
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-source_suffix = [".rst", ".md"]
-
-
-source_parsers = {".md": CommonMarkParser}
+source_suffix = ".rst"
 
 # The master toctree document.
 master_doc = "index"
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -5,5 +5,6 @@ HOME
    :maxdepth: 2
    :caption: Contents:
 
+   notebooks/WHY.ipynb
    notebooks/INSTALL.ipynb
    notebooks/KEYWORDS.ipynb
diff --git a/docs/source/notebooks/INSTALL.ipynb b/docs/source/notebooks/INSTALL.ipynb
@@ -6,8 +6,7 @@
    "source": [
     "# INSTALL\n",
     "Installing `JupyterLibrary` will bring along Robot Framework and SeleniumLibrary. Jupyter components, like `notebook`, `jupyterlab` and `nteract_on_jupyter`, and browser executors (e.g. `chromedriver`, `geckodriver`) and various utilities (e.g. `nodejs`) are up to you, depending on what you want to test. Here are some examples.\n",
-    "\n",
-    "> _Sorry for the mess, haven't actually shipped anything yet... but the [DEV](#DEV) install does kinda work already_"
+    "\n> _Sorry for the mess, haven't actually shipped anything yet... but the [DEV](#DEV) install does kinda work already_"
    ]
   },
   {
@@ -53,7 +52,7 @@
     "`JupyterLibrary` is under active development, and is heavily invested in `conda` because of the complexity of managing browser execution dependencies. But `conda` (rightly) makes it hard to install Random Repos from the Internet, so you'll need a bit of `pip`, too. \n",
     "\n",
     "Here's a complete setup:\n",
-    "```bash\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",
@@ -92,6 +91,9 @@
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
    "version": "3.7.1"
+  },
+  "nteract": {
+   "version": "nteract-on-jupyter@0.35.4"
   }
  },
  "nbformat": 4,
diff --git a/docs/source/notebooks/KEYWORDS.ipynb b/docs/source/notebooks/KEYWORDS.ipynb
@@ -16,6 +16,7 @@
    "source": [
     "## Browser + Server\n",
     "`JupyterLibrary` inherits all of the keywords of [SeleniumLibrary](http://robotframework.org/SeleniumLibrary/SeleniumLibrary.html), and then adds a few more, including the two most important ones:\n",
+    "\n",
     "- **Wait for New Jupyter Server to be Ready**\n",
     "- **Terminate All Jupyter Servers**\n",
     "\n",
diff --git a/docs/source/notebooks/WHY.ipynb b/docs/source/notebooks/WHY.ipynb
@@ -0,0 +1,67 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# WHY"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## ...Jupyter?\n",
+    "\n",
+    "Jupyter clients are some of the most powerful pieces of technology users can run in their web browsers. By developing cross-client capabilities, either as kernel-level extensions, widgets, media types, or other confections, you are helping to advance fields of inquiry you might not even know exist."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## ...Acceptance Tests?\n",
+    "\n",
+    "Unit tests and strongly-typed languages are superb for rapid, confident iteration on even large codebases. But users will be installing **Your Code** next to an unknown number of **Other People's Code**, and then write **Their Code**. If`^H^H` When it breaks, they might not be able to tell that it's the subtle interaction between these things. Testing **All the Code** together, _as your user will use it_, gives you greater confidence in your ability to ship."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## ...JupyterLibrary?\n",
+    "\n",
+    "Powered by [Robot Framework](https://robotframework.org), `JupyterLibrary` allows you to:\n",
+    "\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"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.7.1"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/environment.yml b/environment.yml
@@ -14,7 +14,6 @@ dependencies:
   - nodejs
   - pillow
   - python-chromedriver-binary
-  - recommonmark
   - robotframework >=3.1
   - robotframework-lint
   - robotframework-seleniumlibrary >=3.2
diff --git a/readthedocs.yml b/readthedocs.yml
@@ -0,0 +1,9 @@
+name: robotframework-jupyterlibrary
+type: sphinx
+conda:
+     file: environment.yml
+python:
+  version: 3
+formats:
+  - htmlzip
+  - epub
diff --git a/src/JupyterLibrary/resources/JupyterLab/Commands.robot b/src/JupyterLibrary/resources/JupyterLab/Commands.robot
@@ -10,7 +10,7 @@ Execute JupyterLab Command
     ...   to run a command and ``accept`` any resulting dialogs, then ``close``
     ...   the Command Palette.
     Maybe accept a JupyterLab prompt
-    Maybe Open JupyterLab Sidebar  command-palette
+    Maybe Open JupyterLab Sidebar  Commands
     Input Text    css:${JLAB CSS CMD INPUT}    ${command}
     Wait Until Page Contains Element    css:${JLAB CSS CMD ITEM}
     Click Element    css:${JLAB CSS CMD ITEM}
diff --git a/src/JupyterLibrary/resources/JupyterLab/Output.robot b/src/JupyterLibrary/resources/JupyterLab/Output.robot
@@ -21,12 +21,12 @@ Screenshot Markdown of Active JupyterLab Cell
 Screenshot Each Output of Active JupyterLab Document
     [Arguments]  ${prefix}
     [Documentation]  Capture all of the outputs of the current **Document** as
-    ...   screenshots with a ``prefix``. 
+    ...   screenshots with a ``prefix``.
     ${cells} =  Get WebElements  css:${JLAB CSS ACTIVE DOC CELLS}
     :FOR  ${i}   IN RANGE  ${cells.__len__()}
     \   Click element  ${cells[${i}]}
     \   Run Keyword And Ignore Error    Click element  ${cells[${i + 1}]}
     \   Click element  ${cells[${i}]}
     \   Sleep  0.1s
-    \   Screenshot each output of active cell	${prefix}_cell_${i}
-    \   Screenshot Markdown of active cell	${prefix}_cell_${i}
+    \   Screenshot Each Output of Active JupyterLab Cell	${prefix}_cell_${i}
+    \   Screenshot Markdown of Active JupyterLab Cell 	${prefix}_cell_${i}
diff --git a/src/JupyterLibrary/resources/JupyterLab/Selectors.robot b/src/JupyterLibrary/resources/JupyterLab/Selectors.robot
@@ -12,7 +12,6 @@ ${JLAB CSS BUSY KERNEL}  .jp-Toolbar-kernelStatus.jp-FilledCircleIcon
 ${JLAB CSS CELL}       .jp-Notebook .jp-Cell:last-of-type .jp-InputArea-editor .CodeMirror
 ${JLAB CSS CMD INPUT}    .p-CommandPalette-input
 ${JLAB CSS CMD ITEM}    .p-CommandPalette-item
-${JLAB CSS CMD PALETTE}    li[data-id="command-palette"]
 ${JLAB CSS ICON ADD}  .jp-AddIcon
 ${JLAB CSS ICON RUN}  .jp-RunIcon
 ${JLAB CSS NB TOOLBAR}  .jp-NotebookPanel-toolbar
diff --git a/src/JupyterLibrary/resources/JupyterLab/Shell.robot b/src/JupyterLibrary/resources/JupyterLab/Shell.robot
@@ -7,15 +7,15 @@ Documentation   Keywords for working with the JupyterLab web application
 
 *** Keywords ***
 Open JupyterLab
-    [Arguments]    ${browser}=headlessfirefox  ${nbserver}=${None}  ${url}=${None}   &{configuration}
+    [Arguments]    ${browser}=headlessfirefox  ${nbserver}=${None}  ${url}=${EMPTY}   &{configuration}
     [Documentation]    Open JupyterLab, served from the given (or most-recently-started)
     ...   ``nbserver`` in a ``browser`` (or ``headlessfirefox``) or ``url``,
     ...   then wait for the splash screen.
-    ...   Extra ``configuration`` is passed on to SeleniumLibrary's **Open Browser**.
-    ${url_} =  Run Keyword If    not "${url}"  Get Jupyter Server URL  ${nbserver}
+    ...   Extra ``configuration`` is passed on to SeleniumLibrary's *Open Browser*.
+    ${nbserver_url} =  Run Keyword If    not "${url}"  Get Jupyter Server URL  ${nbserver}
     ${token} =  Run Keyword If    not "${url}"  Get Jupyter Server Token  ${nbserver}
-    ${url} =  Set Variable    "${url}"   ${url}  ${url_}lab?token=${token}
-    Open Browser    url=${url}    browser=${browser}  &{configuration}
+    ${final_url} =  Set Variable If   "${url}"   ${url}  ${nbserver_url}lab?token=${token}
+    Open Browser    url=${final_url}    browser=${browser}  &{configuration}
     Wait for JupyterLab Splash Screen
 
 Wait for JupyterLab Splash Screen
@@ -36,7 +36,7 @@ Click JupyterLab Menu
 Click JupyterLab Menu Item
     [Arguments]    ${label}
     [Documentation]    Click a currently-visible JupyterLab menu item by ``label``.
-    ${item} =    Set Variable  ${JLAB XP MENU ITEM LABEL}\[text() = '${item_label}']
+    ${item} =    Set Variable  ${JLAB XP MENU ITEM LABEL}\[text() = '${label}']
     Wait Until Page Contains Element    ${item}
     Mouse Over    ${item}
     Click Element    ${item}
