Skip to content

Commit 84d6d5c

Browse files
committed
Add basic myst/sphinx site building instructions to README.
1 parent 8239f85 commit 84d6d5c

File tree

1 file changed

+35
-0
lines changed

1 file changed

+35
-0
lines changed

README.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,41 @@ However, we add it here that you can easily have the same user experience in Jup
2929
- Document an accessible development workflow, so that non-experts can contribute.
3030
- Keep the infrastructure as simple as possible.
3131

32+
## Build the site
33+
34+
There are currently two distinct technology stacks that support the
35+
`executable-tutorials` paradigm: a legacy sphinx-based static-site generation
36+
engine, and the newer [myst][myst-org] project.
37+
The `executable-tutorials` repo contains information about both development
38+
patterns, and endeavors to serve as a transition guide between technology
39+
stacks.
40+
41+
By default, the necessary tooling for both technology stacks is installed with
42+
`pip install -r requirements.txt`
43+
44+
### Build with sphinx
45+
46+
```bash
47+
make html
48+
```
49+
50+
The static site can then be viewed by simply opening the index in any browser,
51+
for example::
52+
53+
```bash
54+
firefox _build/html/index.html
55+
```
56+
57+
### Build with `myst`
58+
59+
```bash
60+
myst start --execute
61+
```
62+
63+
This will execute the notebooks, build the site, and set up a server for rendering
64+
the site.
65+
The rendered page can be viewed by opening `localhost:3000` in a browser.
66+
3267
## To Do
3368

3469
- Test execution _of changed tutorials only_ in CI on PR.

0 commit comments

Comments
 (0)