a demo (#8)

deathbeds · Nov 30, 2023 · 4ec0231 · 4ec0231
1 parent 40747df
commit 4ec0231
Show file tree

Hide file tree

Showing 24 changed files with 1,044 additions and 183 deletions.
diff --git a/.binder/conda-linux-64.lock b/.binder/conda-linux-64.lock
diff --git a/.binder/environment.yml b/.binder/environment.yml
@@ -3,16 +3,16 @@ channels:
   - conda-forge/label/jupyterlab_alpha
   - conda-forge/label/notebook_alpha
   - nodefaults
+platforms:
+  - linux-64
 dependencies:
   # more runtimes
   - nodejs >=20,<21
   # jupyter
   - ipywidgets >=8.1.1,<9.0.0
   - jupyterlab >=4.1.0a3,<5.0.0
   - notebook >=7.1.0a0,<8
-  # build
-  - git
-  - flit
+  ### .github/environment.yml ###
   # fix
   - ruff
   - nbstripout
@@ -39,6 +39,7 @@ dependencies:
   - nbconvert
   - pydata-sphinx-theme
   - sphinx-copybutton
-  - sphinx-design
   - sphinxcontrib-mermaid
+  - sphinxext-rediraffe
   ### docs/environment.yml ###
+  ### .github/environment.yml ###
diff --git a/.github/conda-linux-64.lock b/.github/conda-linux-64.lock
diff --git a/.github/environment.yml b/.github/environment.yml
@@ -0,0 +1,37 @@
+channels:
+  - conda-forge
+  - nodefaults
+platforms:
+  - linux-64
+dependencies:
+  ### .github/environment.yml ###
+  # fix
+  - ruff
+  - nbstripout
+  - scour
+  # test
+  - pytest
+  - pytest-cov
+  - pytest-html
+  ### docs/environment.yml ###
+  # runtimes
+  - python >=3.11,<3.12
+  # run
+  - doit-with-toml
+  - importnb
+  - pyyaml
+  - tomli
+  # build
+  - flit-core >=3.9.0,<4
+  - pip
+  - python-build
+  # docs
+  - docutils >=0.19
+  - myst-nb
+  - nbconvert
+  - pydata-sphinx-theme
+  - sphinx-copybutton
+  - sphinxcontrib-mermaid
+  - sphinxext-rediraffe
+  ### docs/environment.yml ###
+  ### .github/environment.yml ###
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
@@ -21,7 +21,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: conda-incubator/setup-miniconda@v3
         with:
-          environment-file: .binder/environment.yml
+          environment-file: .github/conda-linux-64.lock
           miniforge-variant: Mambaforge
           use-mamba: true
       - run: doit bootstrap

diff --git a/.github/workflows/self.yml b/.github/workflows/self.yml
@@ -27,7 +27,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: conda-incubator/setup-miniconda@v3
         with:
-          environment-file: .binder/environment.yml
+          environment-file: .github/conda-linux-64.lock
           miniforge-variant: Mambaforge
           use-mamba: true
       - run: doit bootstrap

diff --git a/README.md b/README.md
@@ -1,13 +1,21 @@
 # jupyak
 
-> Bot-assisted previews of (multiple) PRs to the Jupyter(Lite) stack.
+> get a JupyterLite preview of pull requests across the Jupyter stack
 
-## What does it do?
+## what does it do?
 
-This repo accepts [issues](#how-does-it-work) to build static [preview sites](#how-do-i-get-a-preview-site)
-of Pull Requests to the [Jupyter(Lite) stack](#what-can-it-build).
+This repo accepts [pull requests](#how-does-it-work) that build static [preview sites](#how-do-i-get-a-preview-site) to the [Jupyter(Lite) stack](#what-can-it-build).
 
-## Where does it do it?
+## how do I get a preview site?
+
+- Use the _Request Preview Site_ form to propose a `jupyak_config.json` file to this repo
+  - or manually fork, clone, and build one
+    - the `.toml`, `.yaml`, and `.yml`) extensions are also discovered
+- Make a [pull request][pulls] to this repo
+- Wait for the PR to build a site on ReadTheDocs
+- Make changes to the _PR_ to trigger re-building the preview site
+
+## where does it do it?
 
 - `https://github.com/deathbeds/jupyak`
     - a GitHub repo where the source code for this package, and all Issues, Pull Requests, and source code are stored
@@ -21,36 +29,28 @@ of Pull Requests to the [Jupyter(Lite) stack](#what-can-it-build).
         - PR-based [preview site](#how-do-i-get-a-preview-site)
         - preview of the docs for the site itself
 
-## How do I get a preview site?
-
-- Make an [issue][issues], filling out the form
-- Wait for the bot to make a PR
-- Wait for the PR to build a site on ReadTheDocs
-
-## How does it work?
+## how does it work?
 
 Delivering a preview site uses a few different GitHub Actions workflows and ReadTheDocs.
 
 - A nightly Github Actions job builds `https://deathbeds.github.io/jupyak`
-  - This site includes an accessible HTML form of available PRs, tags, etc. for all
-    supported repos
-  - Filling out this form redirects to a new [issue][issues], requiring a GitHub login
-- The issue is parsed by a lightweight JS-based workflow
-  - It creates a PR with a checked-in file describing the order
-    - If this **fails**, the bot should respond to the original issue with help
-- ReadTheDocs checks out the PR and builds a preview JupyterLite site on a custom
+  - This site includes an HTML form of available PRs, tags, etc. for supported
+    [repos](#what-can-it-build).
+  - Clicking the _submit_ button will open a "new file" GitHub page against this repo
+  - Click _Commit Changes..._
+  - Follow the Pull Request template and submit
+- ReadTheDocs will check out the PR and build a preview JupyterLite site on a custom
     domain
-  - If this **fails**, the site will contain human-readable error logs
-- Additional bot commands on the PR (or original issue)
-  can trigger a rebuild of the site, preserving a copy of last-known-good build
-
+  - If the preview site **fails** to build, the built RTD site will contain
+    human-readable error logs
+- Additional commits on the PR can trigger a rebuild of the site
 
-## What can it build?
+## what can it build?
 
-The bots understand how to work with one or more human-readable HTML URLs of the forms:
+`jupyak` understand how to work with one or more human-readable HTML URLs of the forms:
 
   - `{:repo}/pull/{:pull-id}`
-  - `{:repo}/tree/{:branch-or-commit}`
+  - `{:repo}/tree/{:branch}`
   - `{:repo}/releases/tag/{:tag}`
     - > note that the `/tree/{:tag}` form will fail loudly
 
@@ -70,3 +70,4 @@ The bots understand how to work with one or more human-readable HTML URLs of the
   - https://github.com/jupyterlite/pyodide-kernel
 
 [issues]: https://github.com/deathbeds/jupyak/issues
+[pulls]: https://github.com/deathbeds/jupyak/pulls
diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml
@@ -6,15 +6,24 @@ build:
     python: mambaforge-22.9
   jobs:
     pre_build:
-      - JPYK_ALLOW_NO_CONFIG=1 doit bootstrap
-      - if [ "$(ls -l jupyak_config.* | wc -l)" = "1" ]; then JPYK_LOG_NAME=git doit shave:git:*; fi
-      - if [ "$(ls -l jupyak_config.* | wc -l)" = "1" ]; then JPYK_LOG_NAME=shave doit shave; fi
-      - JPYK_ALLOW_NO_CONFIG=1 doit self:docs:graph
+      - git config --global user.email "jupyak@example.com"
+      - git config --global user.name "jupyak"
+      - JPYK_ALLOW_NO_CONFIG=1 doit bootstrap                             || echo 'ok'
+      # check out everything
+      - JPYK_LOG_NAME=git         doit shave:git:*                        || echo 'ok'
+      # prepare the work conda env
+      - JPYK_LOG_NAME=env         doit shave:env:*                        || echo 'ok'
+      # preflight some JS stuff
+      - JPYK_LOG_NAME=lumino      doit shave:js:lumino:*                  || echo 'ok'
+      # final pass
+      - JPYK_LOG_NAME=shave       doit shave                              || echo 'ok'
+      - JPYK_LOG_NAME=shave2      doit shave                              || echo 'ok'
+      - doit self:docs:deploy:work                                        || echo 'ok'
+      - JPYK_ALLOW_NO_CONFIG=1 doit self:docs:graph                       || echo 'ok'
 
 sphinx:
   builder: html
   configuration: docs/conf.py
-  # fail_on_warning: true
 
 conda:
   environment: docs/environment.yml
diff --git a/docs/_static/css/theme.css b/docs/_static/css/theme.css
@@ -1,4 +1,9 @@
 /* variables */
+:root {
+  --jpyk-color-wasm-purple: #654ff0;
+  --jpyk-color-jupyter-orange: #f37726;
+}
+
 html[data-theme="light"],
 html[data-theme="dark"] {
   --pst-color-primary: #9556cf;
@@ -30,12 +35,21 @@ div.cell_output table  {
 div.cell_output tbody tr:nth-child(odd) {
   background-color: unset !important;
 }
-/* sphinx-design */
-.sd-tab-content {
-  border-top: solid 1px var(--pst-color-border);
-  box-shadow: unset;
+
+.bd-sidebar-primary .sidebar-primary-items__end {
+  margin: 0;
+}
+
+.bd-sidebar-primary {
+  padding-top: 1rem;
 }
 
+.sidebar-primary-item {
+  padding-top: 0 !important;
+  padding-bottom: 1rem;
+}
+
+
 /* mermaid */
 .jp-Mermaid > .mermaid,
 .jp-Mermaid:not(.jp-RenderedMermaid) {
@@ -103,3 +117,32 @@ input[id*="svg-zoom-1"]:checked ~ svg { width: 100%; transition: width 0.5s;}
 input[id*="svg-zoom-2"]:checked ~ svg { width: 200%; transition: width 0.5s;}
 input[id*="svg-zoom-4"]:checked ~ svg { width: 400%; transition: width 0.5s;}
 input[id*="svg-zoom-8"]:checked ~ svg { width: 800%; transition: width 0.5s;}
+
+/* work */
+.work-sidebar {
+  border: solid 2px var(--jpyk-color-wasm-purple);
+  padding: 0;
+}
+
+.work-sidebar-fail {
+  border-color: var(--jpyk-color-jupyter-orange);
+}
+
+.work-sidebar-header {
+  padding: 0.5rem;
+  background-color: var(--jpyk-color-wasm-purple);
+  color: #fff;
+}
+
+.work-sidebar-fail .work-sidebar-header {
+  background-color: var(--jpyk-color-jupyter-orange);
+}
+
+.work-sidebar-content {
+  padding: 1em;
+  padding-bottom: 0;
+}
+
+.work-sidebar .btn {
+  padding: 1rem;
+}
diff --git a/docs/_templates/demo.html b/docs/_templates/demo.html
@@ -0,0 +1,32 @@
+<div class="work-sidebar {% if not lite_links %}work-sidebar-fail{% endif %}">
+  <div class="work-sidebar-header">
+    <i class="fas fa-{% if lite_links %}square-arrow-up-right{% else %}bomb{% endif %}"></i>
+    Preview Site
+  </div>
+  <div class="work-sidebar-content">
+    <blockquote>
+      {% if lite_links %}
+        The preview site built successfully.
+      {% else %}
+        The site <strong>FAILED</strong> to build.
+      {% endif %}
+    </blockquote>
+    {% if lite_links %}
+      <p>
+        {% for frag, info in lite_links.items() %}
+          <a
+            href="{{ pathto('preview/' ~ frag ~ '/index') }}"
+            class="btn btn-primary"
+            target="_blank"
+            title="Try {{ info.label }} in your browser."
+          >
+            <i class="{{ info.icon }}"></i> {{ info.label }}
+          </a>
+        {% endfor %}
+      </p>
+    {% endif %}
+    <p>
+      See the <a href="{{ pathto('work') }}">work page</a> for details.
+    </p>
+  </div>
+</div>