diff --git a/docs/README.md b/docs/README.md index 2100887..b07abe6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -30,3 +30,93 @@ sphinx-apidoc --force --implicit-namespaces --module-first -o reference ../src/p # build docs sphinx-build -n -W --keep-going -b html ./ ./_build/ ``` + +## Interactive notebooks + +### colab +- google product so requires users to have a google account +- does not set up the env automatically so in your notebook include commands for installing dependencies e.g. + ```python + # for colab + !pip install python_package + ``` + +#### Setup +- configure launch_buttons in html_theme_options +- for example: + ```python + html_theme_options = { + ... + "launch_buttons": { + ... + "colab_url": "https://colab.research.google.com", + } + ``` + +### binder +- doesn't require users to install things into env like colab does + +#### Setup +- have repository_url and branch in html_theme_options of conf.py +- also configure launch_buttons in html_theme_options + - [mybinder.org](https://jupyter.org/binder#binderhub) is a free service + - or [deploy your own?](https://jupyter.org/binder#binderhub) +- for example: + ```python + html_theme_options = { + ... + "repository_url": "https://github.com/biosustain/python_package", + "repository_branch": "main", + "launch_buttons" : { + ... + "binderhub_url": "https://mybinder.org", + "notebook_interface": "jupyterlab", + } + } + ``` + + +### thebe +- relies on binder +- turns notebooks to interactive code cells in the docs in the browser. + +#### Extra Requirements +- installation of [`sphinx-thebe`](https://sphinx-thebe.readthedocs.io/en/latest/) e.g. add sphinx-thebe to docs group of [pyproject.toml](../pyproject.toml) +- also add to `extensions` in sphinx conf.py + +#### Setup +- configure thebe in html_theme_options in [conf.py](conf.py) + ```python + html_theme_options = { + ... + # for binder which is used by thebe + "repository_url": "https://github.com/biosustain/python_package", + "repository_branch": "main", + "launch_buttons" : { + ... + "thebe": True + } + } + ``` + - instead can configure thebe repository url and branch in `thebe_config` +- the `selector` in `thebe_config` tells thebe what html element to search for to tun into a runnable code cell +- if wanting to make all code cells runnable set `selector` to `
`s with `class="highlight` + ```python + # thebe options + thebe_config = { + "selector": "div.highlight", + "repository_url": "https://github.com/biosustain/python_package", # optional, will take from html_theme_options + "repository_branch": "main", # optional + } + ``` +- by adding thebe to launch_buttons configuration, there will already be "▶️ Live Code" option from the launch button of the notebook-derived pages +- you can also add an [html button to trigger thebe](https://sphinx-thebe.readthedocs.io/en/latest/configure.html#adding-your-own-button-to-start-thebe) + e.g. for sphinx-book-theme: + this code: + ```markdown + + ``` + produces: + + + diff --git a/docs/conf.py b/docs/conf.py index fbaa22f..67a9e8f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -37,6 +37,7 @@ "sphinx_new_tab_link", # each link opens in a new tab "myst_nb", # Markdown and Jupyter Notebook support "sphinx_copybutton", # add copy button to code blocks + "sphinx_thebe", # make code blocks executable in the browser using Thebe ] # https://myst-nb.readthedocs.io/en/latest/computation/execute.html @@ -86,6 +87,10 @@ # "matplotlib": ("https://matplotlib.org/stable/", None), } +# thebe options +# https://sphinx-thebe.readthedocs.io +thebe_config = {"selector": "div.highlight"} # makes ALL code cells runnable + # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for @@ -97,8 +102,8 @@ # html_logo = "_static/logo-wide.svg" # html_favicon = "_static/logo-square.svg" html_theme_options = { - "github_url": "https://github.com/RasmussenLab/python_package", - "repository_url": "https://github.com/RasmussenLab/python_package", + "github_url": "https://github.com/biosustain/python_package", + "repository_url": "https://github.com/biosustain/python_package", "repository_branch": "main", "home_page_in_toc": True, "path_to_docs": "docs", @@ -107,9 +112,10 @@ "use_repository_button": True, "use_download_button": True, "launch_buttons": { - "colab_url": "https://colab.research.google.com" - # "binderhub_url": "https://mybinder.org", - # "notebook_interface": "jupyterlab", + "colab_url": "https://colab.research.google.com", + "binderhub_url": "https://mybinder.org", + "notebook_interface": "jupyterlab", + "thebe": True, }, "navigation_with_keys": False, } diff --git a/docs/tutorial/tutorial.ipynb b/docs/tutorial/tutorial.ipynb index 8c6f27d..e6bf4fb 100644 --- a/docs/tutorial/tutorial.ipynb +++ b/docs/tutorial/tutorial.ipynb @@ -8,7 +8,9 @@ "# Python Package tutorial\n", "\n", "Run when documentation is build. Building documentation therefore can become\n", - "an minimal integration test for the package." + "an minimal integration test for the package.\n", + "\n", + "" ] }, { @@ -94,6 +96,9 @@ "cell_metadata_filter": "-all", "main_language": "python", "notebook_metadata_filter": "-all" + }, + "language_info": { + "name": "python" } }, "nbformat": 4, diff --git a/docs/tutorial/tutorial.py b/docs/tutorial/tutorial.py index 65d4dfe..5ffeb6a 100644 --- a/docs/tutorial/tutorial.py +++ b/docs/tutorial/tutorial.py @@ -3,6 +3,8 @@ # # Run when documentation is build. Building documentation therefore can become # an minimal integration test for the package. +# +# # %% from python_package import hello_world diff --git a/pyproject.toml b/pyproject.toml index 595531f..1eaf185 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -42,6 +42,7 @@ docs = [ "sphinx-new-tab-link!=0.2.2", "jupytext", "sphinx-copybutton", + "sphinx-thebe" ] # local development options dev = ["black[jupyter]", "ruff", "pytest", "isort", "jupytext"]