Documentation Rewrite

.github/workflows/test.yml

@@ -11,31 +11,28 @@ on:
     - cron: "0 0 * * *"
 
 jobs:
-  test-python:
+  test-python-coverage:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
       - uses: nanasess/setup-chromedriver@master
       - uses: actions/setup-node@v2-beta
         with:
-          node-version: "14.x"
+          node-version: "14"
       - name: Use Latest Python
         uses: actions/setup-python@v2
         with:
-          python-version: 3.9
-      - name: Install latest NPM
-        run: |
-          npm install -g [email protected]
-          npm --version
+          python-version: "3.9"
       - name: Install Python Dependencies
         run: pip install -r requirements/test-run.txt
       - name: Run Tests
-        run: nox -s test -- --headless
-  test-python-versions:
+        env: { "CI": "true" }
+        run: nox -s test_python_suite -- --headless
+  test-python-environments:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: [3.7, 3.8, 3.9]
+        python-version: ["3.7", "3.8", "3.9"]
         os: [ubuntu-latest, macos-latest, windows-latest]
     steps:
       - uses: actions/checkout@v2
@@ -47,60 +44,36 @@ jobs:
         uses: actions/setup-python@v2
         with:
           python-version: ${{ matrix.python-version }}
-      - name: Install latest NPM
-        run: |
-          npm install -g [email protected]
-          npm --version
       - name: Install Python Dependencies
         run: pip install -r requirements/test-run.txt
       - name: Run Tests
-        run: nox -s test -- --headless --no-cov
-  test-javascript:
+        env: { "CI": "true" }
+        run: nox -s test_python -- --headless --no-cov
+  test-docs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
+      - uses: actions/setup-node@v2-beta
         with:
           node-version: "14"
-      - name: Install latest NPM
-        run: |
-          npm install -g [email protected]
-          npm --version
-      - name: Test Javascript
-        working-directory: ./src/client
-        run: |
-          npm install
-          npm test
-          npm run build
-  test-documentation-image:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check out src from Git
-        uses: actions/checkout@v2
-      - name: Get history and tags for SCM versioning to work
-        run: |
-          git fetch --prune --unshallow
-          git fetch --depth=1 origin +refs/tags/*:refs/tags/*
-      - name: Build Docker Image
-        run: docker build . --file docs/Dockerfile
-  test-build-package:
+      - name: Use Latest Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.9"
+      - name: Install Python Dependencies
+        run: pip install -r requirements/test-run.txt
+      - name: Run Tests
+        env: { "CI": "true" }
+        run: nox -s test_docs
+  test-javascript:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v2-beta
         with:
           node-version: "14"
-      - name: Use Latest Python
-        uses: actions/setup-python@v2
-        with:
-          python-version: 3.9
-      - name: Install latest NPM
-        run: |
-          npm install -g [email protected]
-          npm --version
       - name: Install Python Dependencies
-        run: |
-          pip install --upgrade pip
-          pip install -r requirements/build-pkg.txt
-      - name: Test Build Creation
-        run: python setup.py bdist_wheel sdist
+        run: pip install -r requirements/test-run.txt
+      - name: Run Tests
+        env: { "CI": "true" }
+        run: nox -s test_javascript

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/ambv/black
-    rev: 20.8b1
+    rev: 21.12b0
     hooks:
       - id: black
   - repo: https://github.com/PyCQA/flake8
@@ -12,3 +12,7 @@ repos:
     hooks:
       - id: isort
         name: isort
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: "v2.5.1"
+    hooks:
+      - id: prettier

MANIFEST.in

@@ -1,4 +1,2 @@
 recursive-include src/idom/client *
 recursive-include src/idom/web/templates *
-include requirements/prod.txt
-include requirements/extras.txt

docs/Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.8
+FROM python:3.9
 
 WORKDIR /app/
 
@@ -18,7 +18,6 @@ RUN pip install --upgrade pip
 # Install IDOM
 # ------------
 ADD requirements ./requirements
-ADD .git ./.git
 ADD src ./src
 ADD scripts ./scripts
 ADD setup.py ./
@@ -28,16 +27,23 @@ ADD README.md ./
 
 RUN pip install -e .[all]
 
+# Add License
+# -----------
+Add LICENSE /app/
+
 # Build the Docs
 # --------------
-ADD docs/main.py ./docs/
+ADD docs/__init__.py ./docs/
+ADD docs/app.py ./docs/
+ADD docs/examples.py ./docs/
 ADD docs/source ./docs/source
 
 RUN pip install -r requirements/build-docs.txt
-RUN sphinx-build -b html docs/source docs/build
+RUN sphinx-build -W -b html docs/source docs/build
 
 # Define Entrypoint
 # -----------------
 ENV PORT 5000
 ENV IDOM_DEBUG_MODE=1
-CMD python docs/main.py
+ENV IDOM_CHECK_VDOM_SPEC=0
+CMD python scripts/run_docs.py

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/__init__.py

@@ -0,0 +1,4 @@
+from .app import run
+
+
+__all__ = ["run"]

docs/app.py

@@ -0,0 +1,60 @@
+import os
+from logging import getLogger
+from pathlib import Path
+
+from sanic import Sanic, response
+
+from idom.server.sanic import PerClientStateServer
+from idom.widgets import multiview
+
+from .examples import load_examples
+
+
+HERE = Path(__file__).parent
+IDOM_MODEL_SERVER_URL_PREFIX = "/_idom"
+
+logger = getLogger(__name__)
+
+
+IDOM_MODEL_SERVER_URL_PREFIX = "/_idom"
+
+
+def run():
+    app = make_app()
+
+    PerClientStateServer(
+        make_examples_component(),
+        {
+            "redirect_root_to_index": False,
+            "url_prefix": IDOM_MODEL_SERVER_URL_PREFIX,
+        },
+        app,
+    )
+
+    app.run(
+        host="0.0.0.0",
+        port=int(os.environ.get("PORT", 5000)),
+        workers=int(os.environ.get("WEB_CONCURRENCY", 1)),
+        debug=bool(int(os.environ.get("DEBUG", "0"))),
+    )
+
+
+def make_app():
+    app = Sanic(__name__)
+
+    app.static("/docs", str(HERE / "build"))
+
+    @app.route("/")
+    async def forward_to_index(request):
+        return response.redirect("/docs/index.html")
+
+    return app
+
+
+def make_examples_component():
+    mount, component = multiview()
+
+    for example_name, example_component in load_examples():
+        mount.add(example_name, example_component)
+
+    return component