@@ -40,35 +40,40 @@ Images and real-life data make text more engaging and powerful, but be sure what
4040you use is appropriately licensed and available. Here again, even a rough idea
4141for artwork can be polished by others.
4242
43- The NumPy tutorials are a curated collection of
44- [ MyST-NB] ( https://myst-nb.readthedocs.io/ ) notebooks. These notebooks are used
45- to produce static websites and can be opened as notebooks in Jupyter using
46- [ Jupytext] ( https://jupytext.readthedocs.io ) .
43+ ### Building the website
4744
48- > __ Note:__ You should use [ CommonMark] ( https://commonmark.org ) markdown
49- > cells. Jupyter only renders CommonMark.
45+ ``` {note}
46+ The NumPy tutorials are powered by [`jupyter-book`][jb-docs] and the
47+ [`MyST` document engine][mystmd].
48+ See the linked documentation for further details.
49+ ```
50+
51+ [ jb-docs ] : https://jupyterbook.org/stable/
52+ [ mystmd] :
5053
51- ### Why Jupyter Notebooks?
54+ #### Quickstart
5255
53- The choice of Jupyter Notebook in this repo instead of the usual format
54- ( [ reStructuredText, through Sphinx ] ( https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html ) )
55- used in the main NumPy documentation has two reasons :
56+ Set up a development environment with the dependencies listed in
57+ ` requirements.txt ` and ` site/requirements.txt ` .
58+ For example, using the built-in [ ` venv ` ] [ venv ] module :
5659
57- * Jupyter notebooks are a common format for communicating scientific
58- information.
59- * Jupyter notebooks can be launched in [ Binder] ( https://www.mybinder.org ) , so that users can interact
60- with tutorials
61- * rST may present a barrier for some people who might otherwise be very
62- interested in contributing tutorial material.
60+ ``` bash
61+ python -m venv np-tutorials
62+ source np-tutorials/bin/activate
63+ python -m pip install -r requirements.txt -r site/requirements.txt
64+ ```
6365
64- #### Note
66+ [ venv ] : https://docs.python.org/3/library/venv.html
6567
66- You may notice our content is in markdown format ( ` .md ` files). We review and
67- host notebooks in the [ MyST-NB ] ( https://myst-nb.readthedocs.io/ ) format. We
68- accept both Jupyter notebooks ( ` .ipynb ` ) and MyST-NB notebooks ( ` .md ` ).
69- If you want to author ` MyST ` notebooks in jupyterlab, check out the
70- [ jupyterlab_myst ] ( https://mystmd.org/guide/quickstart-jupyter-lab-myst ) extension!
68+ The site can then be built with:
69+
70+ ``` bash
71+ jupyter-book start --execute
72+ ```
7173
74+ This will execute all the notebooks and start a web server to view the rendered
75+ content locally.
76+ View the rendered site by opening the `` localhost:3000 `` in your preferred browser.
7277
7378### Adding your own tutorials
7479
0 commit comments