Skip to content

Commit dafbb93

Browse files
parmentelatparmentelat
committed
update migrating.md
1 parent 66eaa5d commit dafbb93

File tree

1 file changed

+65
-130
lines changed

1 file changed

+65
-130
lines changed

‎migrating.md‎

Lines changed: 65 additions & 130 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,18 @@
11
# migrating out of JB1
22

3-
i.e. to JB2 or astro/starlight and/or codehike
4-
5-
## currently pending at mystmd
6-
7-
### ipywidgets
8-
9-
everything `ipywidgets` seems to be doomed ?
10-
was a bit the same with jb1, although not that serious
11-
this is a problem for
12-
13-
- [ ] nbautoeval (won't work in a static site anyway, unless re-written to use browser-embedded python)
14-
- [ ] interactive visualizations (this being said it was already not working under jb1)
15-
16-
```{admonition} need to dig more
17-
:class: warning
18-
19-
I have seen references to using `jupyterlite` to embed a mini-jupyter in the page, which would solve the problem;
20-
but I have not found any working example yet.
21-
```
22-
23-
### static stuff
24-
25-
things in `_static` don't get found ?
26-
this is a problem for - at least - embedded HTML pages like folium-generated maps; see
27-
28-
- [ ] [https://github.com/jupyter-book/mystmd/issues/189#issuecomment-2725195113](https://github.com/jupyter-book/mystmd/issues/189#issuecomment-2725195113)
29-
- [ ] and/or [https://github.com/jupyter-book/mystmd/issues/1921](https://github.com/jupyter-book/mystmd/issues/1921)
30-
31-
### external urls in TOC
32-
33-
```
34-
⚠️ myst.yml URLs in table of contents are not yet supported:
35-
https://flotpython-exos-ds.readthedocs.io/en/main/ds-tps/images/README-images1-nb.html
36-
```
37-
38-
### slug-ed URLs
39-
40-
really don't like this new trend of botching filenames into slugs;
41-
42-
https://github.com/jupyter-book/mystmd/issues/189#issuecomment-2726427697
43-
44-
https://github.com/jupyter-book/mystmd/issues/670#issuecomment-2726442232
45-
46-
## tooling
47-
48-
- [x] Transform jlab-examples
49-
- [x] Transform flotpython-slides
50-
51-
## what we have now
3+
- [migrating out of JB1](#migrating-out-of-jb1)
4+
- [execution of code cells](#execution-of-code-cells)
5+
- [ipywidgets](#ipywidgets)
6+
- [nbautoeval (won't work in a static site anyway, unless re-written to use browser-embedded python)](#nbautoeval-wont-work-in-a-static-site-anyway-unless-re-written-to-use-browser-embedded-python)
7+
- [static stuff](#static-stuff)
8+
- [slug-ed URLs](#slug-ed-urls)
9+
- [corrections](#corrections)
10+
- [custom themes](#custom-themes)
11+
- [favicons](#favicons)
12+
- [styling](#styling)
13+
- [itables](#itables)
14+
15+
mostly all repos have moved to jb2 as of now
5216

5317
<style>
5418
.todo {
@@ -59,78 +23,73 @@ https://github.com/jupyter-book/mystmd/issues/670#issuecomment-2726442232
5923
}
6024
</style>
6125

62-
| course | orga | tool | comment | URL |
63-
|------------------------:|:------------:|:--------:|:-----------------------:|--------------------------------------------------:|
64-
| `intro` | `ue12-p25` | astro | done | https://intro.info-mines.paris/ |
65-
| `numerique` | `ue12-p25` | jb2 | done | https://numerique.info-mines.paris/ |
66-
| `numerique-exos` | `flotpython` | jb2 | done <br> limitations ? | https://numerique-exos.info-mines.paris/ |
67-
| `slides` | `flotpython` | jb2 | done | https://python.info-mines.paris/ |
68-
| `python-exos` | `flotpython` | jb2 | done<br> limitations ? | https://python-exos.info-mines.paris/ |
69-
| `git` | `ue12-p25` | jb2 | done | https://git.info-mines.paris/ |
70-
| `frontend` | `ue22-p25` | jb2 | done | https://frontend.info-mines.paris/ |
71-
| `backend` | `ue22-p25` | jb2 | done | https://backend.info-mines.paris/ |
72-
| `jupyterlab-examples` | `flotpython` | jb2 | done | https://flotpython.github.io/jupyterlab-examples/ |
73-
| `backend-flask-chatapp` | `ue22-p25` | codehike | not-started | ... |
74-
| `backend-fastapi-notes` | `ue22-p25` | ??? | not-started | ... |
26+
| course | orga | tool | comment | URL |
27+
|------------------------:|:------------:|:-----------------:|:---------------------------------------------:|--------------------------------------------------:|
28+
| `intro` | `ue12-p25` | astro + <br>starlight | done | https://intro.info-mines.paris/ |
29+
| `numerique` | `ue12-p25` | jb2 | done | https://numerique.info-mines.paris/ |
30+
| `numerique-exos` | `flotpython` | jb2 | done | https://numerique-exos.info-mines.paris/ |
31+
| `slides` | `flotpython` | jb2 | done | https://python.info-mines.paris/ |
32+
| `python-exos` | `flotpython` | jb2 | done | https://python-exos.info-mines.paris/ |
33+
| `git` | `ue12-p25` | jb2 | done | https://git.info-mines.paris/ |
34+
| `frontend` | `ue22-p25` | jb2 | done | https://frontend.info-mines.paris/ |
35+
| `backend` | `ue22-p25` | jb2 | done | https://backend.info-mines.paris/ |
36+
| `backend-fastapi-notes` | `ue22-p25` | codehike<br>+next | done | https://backend-fastapi-notes.info-mines.paris/ |
37+
| `backend-flask-chatapp` | `ue22-p25` | codehike | <span class=todo>move to new domain</span> | https://ue22-p24.github.io/backend-flask-chatapp/ |
38+
| `jupyterlab-examples` | `flotpython` | jb2 | <span class=todo>move to new domain</span> | https://flotpython.github.io/jupyterlab-examples/ |
39+
40+
let's summarize the pain points
41+
42+
## execution of code cells
7543

76-
## Notes on domains and URLs
44+
- we now know how to embed a jupyterlite instance in the page; not clear however
45+
how to take advantage of that
7746

78-
- the simple case is with the `ue12-p25` courses
79-
they are now bound to their own domain, e.g. <https://numerique.info-mines.paris/>
80-
- same for `ue22-p25`; that orga is also bound to the info-mines.paris domain in GH, so all is well
81-
- for the `flotpython` orga, we have no custom domain right now; there are several options
82-
- [ ] use the `flotpython.github.io` domain, which is bound to the flotpython orga
83-
- this would give URLs like <https://flotpython.github.io/exos-python/>
84-
- this requires defining BASEURL to be the project name in each repo's gh action (the default when using jb2 template action)
85-
- [ ] use a separate custom domain, e.g. <https://exos-python.flotpython.io/>
86-
- this would require buying and maintaining a domain name, and setting up GH pages to use it
87-
- changes would be needed in the repos themselves (so that the GH action does not set BASEURL to be the project name)
88-
- [x] reuse the `info-mines.paris` domain, e.g. <https://python-exos.info-mines.paris/>
89-
- [x] this would also require setting up the GH orga to bind to that domain (no big deal)
90-
- [x] same comment about BASEURL as above
47+
[![Issue Status](https://img.shields.io/github/issues/detail/state/jupyter-book/mystmd/2318)](https://github.com/jupyter-book/mystmd/issues/2318)
48+
[![Issue Status](https://img.shields.io/github/issues/detail/state/jupyter-book/mystmd/2319)](https://github.com/jupyter-book/mystmd/issues/2319)
9149

92-
```{admonition} apex domain
9350

94-
Note that the toplevel domain `info-mines.paris` is implemented as a
95-
redirect to <https://intro.info-mines.paris/> through this repo-redirect
96-
https://github.com/ue12-p25/portal
97-
```
51+
### ipywidgets
52+
53+
related to the above; with a jlite kernel on board one can produce interactive widgets; but that seems to exclude a build-time execution ?
9854

99-
## JB1
55+
## nbautoeval (won't work in a static site anyway, unless re-written to use browser-embedded python)
10056

101-
## pros
57+
- [ ] interactive visualizations (this being said it was already not working under jb1)
10258

103-
- [ ] all supports were using this as of p24
104-
- [ ] easy recipe to publish on readthedocs; which supports several branches simultaneously
59+
## static stuff
60+
61+
[![Issue Status](https://img.shields.io/github/issues/detail/state/jupyter-book/mystmd/1921)](https://github.com/jupyter-book/mystmd/issues/1921)
62+
63+
this is a problem for - at least - embedded HTML pages like folium-generated maps; see
64+
65+
- [ ] [https://github.com/jupyter-book/mystmd/issues/189#issuecomment-2725195113](https://github.com/jupyter-book/mystmd/issues/189#issuecomment-2725195113)
10566

106-
### cons
67+
## slug-ed URLs
10768

108-
- [ ] **no longer supported**
109-
- [ ] runs on sphinx, sloowww
110-
- [ ] can **only** publish on readthedocs ? (probably doable on github pages too but we have no experience of that as of yet)
69+
[![Issue Status](https://img.shields.io/github/issues/detail/state/jupyter-book/mystmd/2316)](https://github.com/jupyter-book/mystmd/issues/2316)
11170

112-
---
71+
## corrections
11372

114-
## JB2
73+
- there remains an issue with **hidden content being searchable**; see
74+
[![Issue Status](https://img.shields.io/github/issues/detail/state/jupyter-book/mystmd/2312)](https://github.com/jupyter-book/mystmd/issues/2312)
75+
- the `hidden` flag now works as expected
76+
- currently relying on tampermonkey on an individual basis, but using a custom theme could be the way to go do make it widely available
11577

116-
### pros
78+
## custom themes
11779

118-
- modern, and supported, alternative to jb1
119-
- execute codes in notebooks
120-
- fast DX
121-
- see also the doc in <https://mystmd.org/guide/directives>
80+
-> see https://github.com/jupyter-book/mystmd/issues/2317
12281

123-
### cons
82+
for a new scheme to expose built-in themes as GH releases
12483

125-
- must publish on github pages for now, and so no multiple branches at the same time
84+
[![Issue Status](https://img.shields.io/github/issues/detail/state/jupyter-book/mystmd/2317)](https://github.com/jupyter-book/mystmd/issues/2317)
12685

127-
### pain points / todo list
86+
## favicons
12887

129-
- [ ] still misses the cheat shortcut to get corrections
130-
- [ ] need to find a way to embed a piece of JS
131-
- [ ] the corriges do not seem to be evaluated like they were under sphinx/jb1
132-
- [ ] put it all together; may have an impact on styling...
133-
- [ ] favicons on the published end ? <https://ue12-p25.github.io/numerique/> has none but the local one is fine
88+
used a workaround which is to use .ico files instead of .svg
89+
90+
## styling
91+
92+
we have a common style_jb2.css that takes care of most details; might need some further adjustments one day but good enough for now
13493

13594
- [ ] styling
13695
- [x] lists
@@ -142,30 +101,6 @@ https://github.com/jupyter-book/mystmd/issues/670#issuecomment-2726442232
142101
- [ ] are not centered; not exactly serious either
143102
- [ ] hovering used to outline the whole row, now just the first cell in the row
144103

145-
#### second order
146-
147-
- [ ] not sure about the slug thing; can we override the default function ?
148-
- [ ] would be nice to be able to rename `myst.yml` into `_myst.yml`
149-
- [ ] inline images ? right now they cause a new paragraph to be created
150-
- [ ] jupyterlite embeddings not working at all
151-
152-
#### fixed
153-
154-
- [x] equation from
155-
http://localhost:3000/numpy-tp-dices-advanced-nb#version-pour-les-d-butants
156-
rendered oddly (but better than jb1 for that matter)
157-
fixed by adding an extra {equation} environment around it
158-
159-
---
160-
161-
## astro / starlight
162-
163-
### pros
164-
165-
- [ ] large community
166-
- [ ] very robust
167-
- [ ] very complete
168-
169-
### cons
104+
## itables
170105

171-
- [ ] not notebooks, code is not executed...
106+
not quite sure where we are there, we may need to add a recipe notebook in here to assess the situation

0 commit comments

Comments
 (0)