diff --git a/book/installation-and-setup/figures/jupyterlab.png b/book/installation-and-setup/figures/jupyterlab.png new file mode 100644 index 0000000..e745d2c Binary files /dev/null and b/book/installation-and-setup/figures/jupyterlab.png differ diff --git a/book/installation-and-setup/pixi.md b/book/installation-and-setup/pixi.md index 17043ce..2c9e634 100644 --- a/book/installation-and-setup/pixi.md +++ b/book/installation-and-setup/pixi.md @@ -1,21 +1,49 @@ -# Installing and running with Pixi +# Installing and running Teachbooks with Pixi -- Install pixi +> Install Pixi once, and you don't have to worry about installing the correct Python version and TeachBooks dependencies yourself. -In the root file of the TB: +Pixi is a package management tool that allows you to install Python, TeachBooks, and other dependencies using a single `pixi.toml` file. We created this file for you, so you only need to install [pixi from here](https://pixi.prefix.dev/latest/installation/). Pixi is available for Windows, macOS, and Linux. -- run `pixi install` +We present Pixi here as an alternative installation and workflow to the approach presented in the rest of this documentation. When using Pixi, you do not need to separately install Python, TeachBooks, JupyterLab, or manage a virtual environment. Simply start making your book using the [ten steps](https://teachbooks.tudelft.nl/jupyter-book-manual/draft/external/template/README.html#your-first-teachbook-using-the-github-template) and install the project environment as described below. -This will install teachbooks and the most common dependecies. +> If you already have a TeachBooks project, download this [pixi.toml file](../../pixi.toml), place it in the root folder of your project, and follow the steps below. -three tasks: + + +Using the terminal, navigate to the root folder of your project and run `pixi install`. This will install all necessary software and packages - these are installed in the project folder in `.pixi/`. + +In the pixi.toml file we have created three tasks: - `pixi run editor` this will start jupyterlab as the editor for both markdown and jupyternotebooks -- `pixi run serve` starts a server -- `pixi run teachbooks` builds the book (equivalent to `teachbooks build book` as described here) - - +- `pixi run server` starts a server +- `pixi run teachbooks` builds the book (equivalent to `teachbooks build book` as described [here](https://teachbooks.tudelft.nl/jupyter-book-manual/draft/installation-and-setup/jupyter-book-setup.html#build-a-book)) +## Add dependencies +In the pixi.toml file, we included some of the most used depencies. If you want to add packages, use `pixi add ` or if it is only available through pypi, use `pixi add --pypi `. Pixi adds the dependency to your project and updates the environment. ## Editing with Jupyter lab -Something about Jupyter lab \ No newline at end of file +As an alternative to VSC, JupyterLab can be used to edit of your Jupyter Notebook and Markdown files. Start JupyterLab by running `pixi run editor` + +```{figure} figures/jupyterlab.png +--- +width: 50% +name: fig_juplab_editor +--- +Running `pixi run editor` opens jupyterlab as editor. +``` + +You can preview the content by rightclicking the markdown document and open with markdownpreviewer. Once finished with editing, go back to the terminal and hit `ctrl + c` to stop the Jupyter server. + +## Cleaning up an unused project + +The Pixi environment can take up considerable disk space. If you don't plan to work on your TeachBook for a while, you can remove the installed environment with: + +`pixi clean` + +This removes the software and packages installed in the project's .pixi/ folder. Your pixi.toml and pixi.lock files are kept, so you can recreate the environment later by running: + +`pixi install` + +```{note} +If you have multiple Teachbooks, it seems as if they all take a lot of memory. This isn't really the case as pixi makes smart use of links between them. +``` \ No newline at end of file diff --git a/pixi.lock b/pixi.lock index 38940d5..25afbbe 100644 --- a/pixi.lock +++ b/pixi.lock @@ -229,6 +229,7 @@ environments: - pypi: https://files.pythonhosted.org/packages/37/86/d45756beaeb4b9b06125599b429451f8640b5db6f019d606f33c85743fd4/jupyter_book-1.0.4.post1-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/64/6b/67b87da9d36bff9df7d0efbd1a325fa372a43be7158effaf43ed7b22341d/jupyter_cache-1.0.1-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/f6/54/af203c61a0550c232ed5e859d2c98f3fe80d1248b6ea1c4d4d5621fa08c9/jupyterbook_patches-1.15.0-py3-none-any.whl + - pypi: https://files.pythonhosted.org/packages/2b/08/ad5d4d383807ca379c02b8fa94f744c30ea0929a9b3953a19b00bea52b8b/jupyterlab_myst-2.7.0-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/b5/40/23569737873cc9637fd488606347e9dd92b9fa37ba4fcda1f98ee5219a97/latexcodec-3.0.1-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/eb/3d/e34b19cd144071c583317268c4feb2c59c03ac57eef69753410c7abb11c0/linkify_it_py-2.1.1-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/42/d7/1ec15b46af6af88f19b8e5ffea08fa375d433c998b8a7639e76935c14f1f/markdown_it_py-3.0.0-py3-none-any.whl @@ -239,6 +240,8 @@ environments: - pypi: https://files.pythonhosted.org/packages/44/f6/775eb92e865b28cdb4ad1f2bed7a5446197516f76b58a950faa3be3fd08d/pybtex-0.26.1-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/11/b1/ce1f4596211efb5410e178a803f08e59b20bedb66837dcf41e21c54f9ec1/pybtex_docutils-1.0.3-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/e2/0d/8ba33fa83a7dcde13eb3c1c2a0c1cc29950a048bfed6d9b0d8b6bd710b4c/pydata_sphinx_theme-0.16.1-py3-none-any.whl + - pypi: https://files.pythonhosted.org/packages/3e/b9/3766cc361d93edb2ce81e2e1f87dd98f314d7d513877a342d31b30741680/pypng-0.20220715.0-py3-none-any.whl + - pypi: https://files.pythonhosted.org/packages/37/61/f07226075c347897937d4086ef8e55f0a62ae535e28069884ac68d979316/PyQRCode-1.2.1.tar.gz - pypi: https://files.pythonhosted.org/packages/b8/0c/51f6841f1d84f404f92463fc2b1ba0da357ca1e3db6b7fbda26956c3b82a/ruamel_yaml-0.19.1-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/95/9c/c510029fc6ef33a6275cd2c5d3cecd6613dfd6aa401d57c54f1c18852ccf/setuptools-84.0.0-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/4c/07/2ebca9b11fb9be7340a818d8d6f63feaebb146be2c4afbd6061701d6df6e/snowballstemmer-3.1.1-py3-none-any.whl @@ -284,6 +287,7 @@ environments: - pypi: git+https://github.com/TeachBooks/TeachBooks-Favourites.git#ad0f301f83effb9322a5460f444d88878b30a75b - pypi: https://files.pythonhosted.org/packages/7f/24/77b78c112c60e2ddb16351e77f9a108628a6c3c18a618815112d79d374a2/teachbooks_fetch-0.0.1-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/01/d0/99a7a3e3cce5d83566567c484cce9f2c5874c22da4cf2d420647233dbc81/teachbooks_questions-0.2.1-py3-none-any.whl + - pypi: https://files.pythonhosted.org/packages/3e/70/86d1bd35bcf06cdb0aaf59cdec3932cec21750dd276b69856221e25ea6d5/teachbooks_sphinx_grasple-1.3.0-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/05/77/8c5a7237bc99221408f12b629210b8f2176bcccfca916c09edfa8eb048e3/teachbooks_sphinx_tippy-1.0.15-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/24/74/f356db22f82eba6fd559128ae31222564f1e9e1e8b46a6ff93262621a9a2/teachbooks_zoomies-0.2.4-py3-none-any.whl - pypi: https://files.pythonhosted.org/packages/61/73/d21edf5b204d1467e06500080a50f79d49ef2b997c79123a536d4a17d97c/uc_micro_py-2.0.0-py3-none-any.whl @@ -1487,6 +1491,18 @@ packages: - pkg:pypi/jupyterlab?source=compressed-mapping size: 13178193 timestamp: 1786398793317 +- pypi: https://files.pythonhosted.org/packages/2b/08/ad5d4d383807ca379c02b8fa94f744c30ea0929a9b3953a19b00bea52b8b/jupyterlab_myst-2.7.0-py3-none-any.whl + name: jupyterlab-myst + version: 2.7.0 + sha256: 7c66aae898a5b0db84b1d4b83fa68d5d37f846b4f891621de78abb960678e70e + requires_dist: + - jupyter-server>=2.0.1,<3 ; sys_platform != 'emscripten' + - coverage ; extra == 'test' + - pytest ; extra == 'test' + - pytest-asyncio ; extra == 'test' + - pytest-cov ; extra == 'test' + - pytest-jupyter[server]>=0.6.0 ; extra == 'test' + requires_python: '>=3.8' - conda: https://conda.anaconda.org/conda-forge/noarch/jupyterlab_pygments-0.3.0-pyhd8ed1ab_2.conda sha256: dc24b900742fdaf1e077d9a3458fd865711de80bca95fe3c6d46610c532c6ef0 md5: fd312693df06da3578383232528c468d @@ -2781,6 +2797,16 @@ packages: - pkg:pypi/pyparsing?source=hash-mapping size: 110893 timestamp: 1769003998136 +- pypi: https://files.pythonhosted.org/packages/3e/b9/3766cc361d93edb2ce81e2e1f87dd98f314d7d513877a342d31b30741680/pypng-0.20220715.0-py3-none-any.whl + name: pypng + version: 0.20220715.0 + sha256: 4a43e969b8f5aaafb2a415536c1a8ec7e341cd6a3f957fd5b5f32a4cfeed902c +- pypi: https://files.pythonhosted.org/packages/37/61/f07226075c347897937d4086ef8e55f0a62ae535e28069884ac68d979316/PyQRCode-1.2.1.tar.gz + name: pyqrcode + version: 1.2.1 + sha256: fdbf7634733e56b72e27f9bce46e4550b75a3a2c420414035cae9d9d26b234d5 + requires_dist: + - pypng>=0.0.13 ; extra == 'png' - conda: https://conda.anaconda.org/conda-forge/win-64/pyside6-6.11.2-py314h447aaf0_0.conda sha256: bf1553eebc31e8ba04689639e8ce235c3df5317414f0c4a11417f238297f1b17 md5: 7c3ccff96dbc9f8e3c40142c7594ec34 @@ -3892,6 +3918,52 @@ packages: requires_dist: - sphinx requires_python: '>=3.10' +- pypi: https://files.pythonhosted.org/packages/3e/70/86d1bd35bcf06cdb0aaf59cdec3932cec21750dd276b69856221e25ea6d5/teachbooks_sphinx_grasple-1.3.0-py3-none-any.whl + name: teachbooks-sphinx-grasple + version: 1.3.0 + sha256: 414e20e9036a47b24d3d09b34fa16cf3f7b2758f9e24fb47da0496b3d70c1878 + requires_dist: + - pypng + - pyqrcode + - sphinx-book-theme + - sphinx>=4 + - beautifulsoup4 ; extra == 'all' + - black ; extra == 'all' + - coverage ; extra == 'all' + - docutils>=0.15,<0.19 ; extra == 'all' + - flake8>=3.7.0,<3.8.0 ; extra == 'all' + - matplotlib ; extra == 'all' + - myst-nb~=0.17.1 ; extra == 'all' + - pre-commit ; extra == 'all' + - pypng ; extra == 'all' + - pyqrcode ; extra == 'all' + - pytest-cov ; extra == 'all' + - pytest-regressions ; extra == 'all' + - pytest>=3.6,<4 ; extra == 'all' + - sphinx-book-theme ; extra == 'all' + - sphinx-exercise ; extra == 'all' + - sphinx>=4,<6 ; extra == 'all' + - texsoup ; extra == 'all' + - black ; extra == 'code-style' + - flake8>=3.7.0,<3.8.0 ; extra == 'code-style' + - pre-commit ; extra == 'code-style' + - myst-nb~=0.17.1 ; extra == 'rtd' + - sphinx-book-theme ; extra == 'rtd' + - sphinx-exercise ; extra == 'rtd' + - sphinx>=4,<6 ; extra == 'rtd' + - beautifulsoup4 ; extra == 'testing' + - coverage ; extra == 'testing' + - docutils>=0.15,<0.19 ; extra == 'testing' + - matplotlib ; extra == 'testing' + - myst-nb~=0.17.1 ; extra == 'testing' + - pypng ; extra == 'testing' + - pyqrcode ; extra == 'testing' + - pytest-cov ; extra == 'testing' + - pytest-regressions ; extra == 'testing' + - pytest>=3.6,<4 ; extra == 'testing' + - sphinx>=4,<6 ; extra == 'testing' + - texsoup ; extra == 'testing' + requires_python: '>=3.8' - pypi: https://files.pythonhosted.org/packages/05/77/8c5a7237bc99221408f12b629210b8f2176bcccfca916c09edfa8eb048e3/teachbooks_sphinx_tippy-1.0.15-py3-none-any.whl name: teachbooks-sphinx-tippy version: 1.0.15 diff --git a/pixi.toml b/pixi.toml index bb52dcb..3b9a135 100644 --- a/pixi.toml +++ b/pixi.toml @@ -21,3 +21,5 @@ teachbooks = ">=0.2.5, <0.3" teachbooks-favourites = { git = "https://github.com/TeachBooks/TeachBooks-Favourites.git" } sphinx-inline-tabs = ">=2025.12.21.14, <2026" sphinx-apa-references = ">=1.0.1, <2" +jupyterlab-myst = ">=2.7.0, <3" +teachbooks-sphinx-grasple = ">=1.3.0, <2"