fix up docker image

Author: rmorshea

docs/Dockerfile

@@ -33,7 +33,6 @@ Add LICENSE /app/
 
 # Build the Docs
 # --------------
-ADD run_docs.py ./
 ADD docs/__init__.py ./docs/
 ADD docs/app.py ./docs/
 ADD docs/examples.py ./docs/

docs/README.md

@@ -0,0 +1,18 @@
+# IDOM's Documentation
+
+We provide two main ways to run the docs. Both use `nox` which has a `noxfile.py` at the
+root of the repository. Running the docs with `nox -s docs` will start up an iteractive
+session which will rebuild the docs any time a file is modified. Using `nox -s
+docs_in_docker` on the other hand, will build a docker image and run the docs from
+there. The latter command mimics how the docs will behave in production. As such, if any
+changes to the core of the documentation are made (i.e. to non-`*.rst` files), then you
+should run a manual test of the documentation using the `docs_in_docker` session.
+
+If you with to build and run the docs by hand you need to perform two commands, each
+being run from the root of the repository:
+
+- `sphinx-build -b html docs/source docs/build`
+- `python scripts/run_docs.py`
+
+The first command constructs the static HTML and any Javascript. The latter actually
+runs the web server that serves the content.

docs/source/_static/custom.js

@@ -1911,7 +1911,7 @@ function mountLayoutWithReconnectingWebSocket(
   const updateHookPromise = new LazyPromise();
 
   socket.onopen = (event) => {
-    console.log(`Connected.`);
+    console.info(`IDOM WebSocket connected.`);
 
     if (mountState.everMounted) {
       reactDom.unmountComponentAtNode(element);
@@ -1932,7 +1932,7 @@ function mountLayoutWithReconnectingWebSocket(
 
   socket.onclose = (event) => {
     if (!maxReconnectTimeout) {
-      console.log(`Connection lost.`);
+      console.info(`IDOM WebSocket connection lost.`);
       return;
     }
 
@@ -1941,7 +1941,7 @@ function mountLayoutWithReconnectingWebSocket(
       mountState
     );
 
-    console.log(`Connection lost, reconnecting in ${reconnectTimeout} seconds`);
+    console.info(`IDOM WebSocket connection lost. Reconnecting in ${reconnectTimeout} seconds...`);
 
     setTimeout(function () {
       mountState.reconnectAttempts++;

noxfile.py

@@ -85,6 +85,7 @@ def docs(session: Session) -> None:
 
 @nox.session
 def docs_in_docker(session: Session) -> None:
+    """Build a docker image for the documentation and run it to mimic production"""
     session.run(
         "docker",
         "build",
@@ -120,7 +121,7 @@ def test(session: Session) -> None:
 
 @nox.session
 def test_short(session: Session) -> None:
-    """Run the complete test suite"""
+    """Run a shortened version of the test suite"""
     session.notify("test_suite", posargs=session.posargs)
     session.notify("test_docs")
 
@@ -192,6 +193,7 @@ def test_docs(session: Session) -> None:
 
 @nox.session
 def tag(session: Session):
+    """Create a new git tag"""
     try:
         session.run(
             "git",
@@ -226,6 +228,7 @@ def tag(session: Session):
 
 @nox.session
 def update_version(session: Session) -> None:
+    """Update the version of all Python and Javascript packages in this repo"""
     if len(session.posargs) > 1:
         session.error("To many arguments")
 

scripts/README.md

@@ -1,4 +1,5 @@
 # Scripts
 
-All scripts should be run from the repository root
-(typically using [`nox`](https://nox.thea.codes/en/stable/)).
+All scripts should be run from the repository root (typically using
+[`nox`](https://nox.thea.codes/en/stable/)). Use `nox --list` to see the list of
+available scripts.

scripts/run_docs.py

@@ -1,5 +1,13 @@
-from docs import run
+import os
+import sys
+
+
+# all scripts should be run from the repository root so we need to insert cwd to path
+# to import docs
+sys.path.insert(0, os.getcwd())
 
 
 if __name__ == "__main__":
+    from docs import run
+
     run()