├── .binder ├── README ├── apt.txt ├── postBuild ├── requirements.txt └── start ├── .circleci ├── artifact_path ├── artifacts.html └── config.yml ├── .editorconfig ├── .github ├── dependabot.yml └── workflows │ ├── html-macos.yml │ ├── linkcheck.yml │ ├── publish.yml │ └── version-matrix.yml ├── .gitignore ├── .readthedocs.yml ├── CONTRIBUTING.rst ├── LICENSE ├── MANIFEST.in ├── NEWS.rst ├── README.rst ├── doc ├── README ├── a-markdown-file.md ├── a-normal-rst-file.rst ├── allow-errors-per-cell.ipynb ├── allow-errors.ipynb ├── code-cells.ipynb ├── conf.py ├── configuration.ipynb ├── configuring-kernels.ipynb ├── contributing.rst ├── custom-css.ipynb ├── custom-formats.pct.py ├── executing-notebooks.ipynb ├── fallback_theme.txt ├── favicon.svg ├── gallery │ ├── cell-metadata.ipynb │ ├── cell-tag.ipynb │ ├── cinque-rst.ipynb │ ├── default-thumbnail.ipynb │ ├── due-rst.pct.py │ ├── gallery-with-links.ipynb │ ├── gallery-with-nested-documents.ipynb │ ├── matplotlibrc │ ├── multiple-outputs.ipynb │ ├── no-thumbnail.ipynb │ ├── thumbnail-from-conf-py.ipynb │ └── uno-rst.ipynb ├── hidden-cells.ipynb ├── images │ ├── notebook_icon.png │ ├── python_logo.svg │ ├── raw_cells_jupyter_notebook.png │ └── raw_cells_jupyterlab.png ├── index.rst ├── installation.ipynb ├── links.ipynb ├── markdown-cells.ipynb ├── matplotlibrc ├── never-execute.ipynb ├── orphan.ipynb ├── pre-executed.ipynb ├── prolog-and-epilog.ipynb ├── raw-cells.ipynb ├── references.bib ├── references.rst ├── requirements.txt ├── subdir │ ├── a-notebook-in-a-subdir.ipynb │ ├── gallery.ipynb │ └── toctree.ipynb ├── timeout.ipynb ├── usage.ipynb ├── version-history.rst └── yet-another.ipynb ├── git_rebase_theme_branches.sh ├── include-in-latex ├── README.md ├── _templates │ └── latex.tex_t ├── conf.py ├── latexmkrc ├── my-latex-document.tex ├── my-own-references.bib ├── pygmentize.py ├── sphinxlatexindbibtoc.sty ├── sphinxlatexstyleheadings.sty └── sphinxoptionsgeometry.sty ├── pyproject.toml ├── setup.py ├── src └── nbsphinx │ ├── __init__.py │ ├── _static │ ├── nbsphinx-broken-thumbnail.svg │ ├── nbsphinx-code-cells.css_t │ ├── nbsphinx-gallery.css │ └── nbsphinx-no-thumbnail.svg │ └── _texinputs │ └── nbsphinx.sty └── theme_comparison.py /.binder/README: -------------------------------------------------------------------------------- 1 | This directory holds configuration files for https://mybinder.org/. 2 | 3 | The notebooks that comprise the documentation can be accessed with this link: 4 | https://mybinder.org/v2/gh/spatialaudio/nbsphinx/master?filepath=doc 5 | 6 | To check out a different version, just replace "master" with the desired 7 | branch/tag name or commit hash. 8 | 9 | To use JupyterLab, use: 10 | https://mybinder.org/v2/gh/spatialaudio/nbsphinx/master?urlpath=lab/tree/doc 11 | -------------------------------------------------------------------------------- /.binder/apt.txt: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/spatialaudio/nbsphinx/b7430090715c68eb1846d677b997c74892d51af1/.binder/apt.txt -------------------------------------------------------------------------------- /.binder/postBuild: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | set -e 4 | 5 | # add your shell commands here 6 | -------------------------------------------------------------------------------- /.binder/requirements.txt: -------------------------------------------------------------------------------- 1 | matplotlib 2 | ipympl 3 | pandas 4 | ipywidgets 5 | jupytext 6 | jupyterlab>=3 7 | -------------------------------------------------------------------------------- /.binder/start: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # https://mybinder.readthedocs.io/en/latest/config_files.html#start-run-code-before-the-user-sessions-starts 4 | 5 | export MY_DUMMY_VARIABLE="Hello from .binder/start!" 6 | 7 | exec "$@" 8 | -------------------------------------------------------------------------------- /.circleci/artifact_path: -------------------------------------------------------------------------------- 1 | 0/artifacts.html 2 | -------------------------------------------------------------------------------- /.circleci/artifacts.html: -------------------------------------------------------------------------------- 1 | 2 | CircleCI artifacts for nbsphinx 3 | 21 | 25 |
26 | 27 | 28 |
29 | -------------------------------------------------------------------------------- /.circleci/config.yml: -------------------------------------------------------------------------------- 1 | # Python CircleCI 2.0 configuration file 2 | # 3 | # Check https://circleci.com/docs/2.0/language-python/ for more details 4 | # 5 | version: 2 6 | jobs: 7 | build_docs: 8 | docker: 9 | - image: texlive/texlive 10 | 11 | working_directory: ~/checkout 12 | 13 | environment: 14 | PIP_INSTALL: python -m pip install --progress-bar off --upgrade 15 | SPHINX: python -m sphinx -W --keep-going --color 16 | 17 | steps: 18 | - checkout 19 | 20 | - store_artifacts: 21 | name: Uploading overview page 22 | path: .circleci/artifacts.html 23 | destination: artifacts.html 24 | 25 | - run: 26 | name: Installing apt Packages 27 | command: | 28 | apt-get -y update 29 | apt-get install -y --no-install-recommends python3-venv librsvg2-bin binutils pandoc 30 | 31 | - restore_cache: 32 | keys: 33 | - v1-deps-{{ .Branch }}-{{ checksum "doc/requirements.txt" }} 34 | # fallbacks 35 | - v1-deps-{{ .Branch }}- 36 | - v1-deps- 37 | 38 | - run: 39 | name: Set up venv 40 | command: | 41 | python3 -m venv .venv 42 | echo "source .venv/bin/activate" >> $BASH_ENV 43 | 44 | - run: 45 | name: Installing Sphinx 46 | # See https://github.com/sphinx-doc/sphinx/issues/12331 47 | command: | 48 | $PIP_INSTALL "sphinx !=7.3.0, != 7.3.1, != 7.3.2, != 7.3.3, != 7.3.4, != 7.3.5, != 7.3.6, != 7.3.7" 49 | 50 | - run: 51 | name: Installing nbsphinx 52 | command: | 53 | $PIP_INSTALL . 54 | 55 | - run: 56 | name: Installing doc Dependencies 57 | command: | 58 | $PIP_INSTALL -r doc/requirements.txt 59 | 60 | - save_cache: 61 | paths: 62 | - ~/.cache/pip 63 | key: v1-deps-{{ .Branch }}-{{ checksum "doc/requirements.txt" }} 64 | 65 | - run: 66 | name: Show pandoc version 67 | command: | 68 | pandoc --version 69 | 70 | - run: 71 | name: Building HTML 72 | command: | 73 | $SPHINX -d build/doctrees doc build/html -b html 74 | 75 | - store_artifacts: 76 | name: Uploading HTML files 77 | path: build/html 78 | destination: html 79 | 80 | - run: 81 | name: Building LaTeX 82 | command: | 83 | $SPHINX -d build/doctrees doc build/latex -b latex 84 | 85 | - run: 86 | name: Building PDF 87 | command: | 88 | cd build/latex 89 | latexmk -pdflua 90 | 91 | - store_artifacts: 92 | name: Uploading PDF file 93 | path: build/latex/nbsphinx.pdf 94 | destination: nbsphinx.pdf 95 | 96 | - run: 97 | name: Building LaTeX document with nbsphinx docs as chapter 98 | # NB: There is a warning about :footcite:, so we are not using "-W" 99 | command: | 100 | cd include-in-latex 101 | python -m sphinx --color ../doc _build -c . -b latex 102 | 103 | - run: 104 | name: Building PDF of above 105 | command: | 106 | cd include-in-latex 107 | latexmk 108 | 109 | - store_artifacts: 110 | name: Uploading another PDF file 111 | path: include-in-latex/my-latex-document.pdf 112 | destination: my-latex-document.pdf 113 | 114 | workflows: 115 | version: 2 116 | build-me-my-docs: 117 | jobs: 118 | - build_docs 119 | -------------------------------------------------------------------------------- /.editorconfig: -------------------------------------------------------------------------------- 1 | # http://editorconfig.org 2 | 3 | root = true 4 | 5 | [*] 6 | end_of_line = lf 7 | charset = utf-8 8 | max_line_length = 80 9 | indent_style = space 10 | indent_size = 4 11 | insert_final_newline = true 12 | trim_trailing_whitespace = true 13 | 14 | [*.py] 15 | max_line_length = 79 16 | 17 | [*.ipynb] 18 | max_line_length = off 19 | 20 | [*.yml] 21 | indent_size = 2 22 | max_line_length = off 23 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: "github-actions" 4 | directory: "/" 5 | schedule: 6 | interval: "weekly" 7 | -------------------------------------------------------------------------------- /.github/workflows/html-macos.yml: -------------------------------------------------------------------------------- 1 | name: Build HTML on macOS 2 | on: [push, pull_request] 3 | env: 4 | PYTHONWARNINGS: error 5 | PIP: python -m pip 6 | SPHINX: python -m sphinx -W --keep-going --color 7 | jobs: 8 | html-macos: 9 | runs-on: macos-latest 10 | steps: 11 | - name: Clone repo 12 | uses: actions/checkout@v4 13 | with: 14 | fetch-depth: 0 15 | - name: Install pandoc 16 | run: | 17 | brew install pandoc 18 | - name: Set up Python 19 | uses: actions/setup-python@v5 20 | with: 21 | python-version: 3 22 | - name: Double-check Python version 23 | run: | 24 | python --version 25 | - name: Install Python package 26 | env: 27 | # DeprecationWarning: Unimplemented abstract methods {'locate_file'} 28 | # https://github.com/pypa/pip/issues/11684 29 | PYTHONWARNINGS: error,default::DeprecationWarning 30 | run: | 31 | $PIP install . 32 | - name: Install docs dependencies 33 | env: 34 | # DeprecationWarning: Unimplemented abstract methods {'locate_file'} 35 | # https://github.com/pypa/pip/issues/11684 36 | PYTHONWARNINGS: error,default::DeprecationWarning 37 | run: | 38 | $PIP install -r doc/requirements.txt 39 | - name: Build HTML 40 | env: 41 | # There is a weird warning from jupyter_core (https://github.com/jupyter/jupyter_core/issues/398) 42 | # RemovedInSphinx10Warning: 'sphinx.util.import_object' is deprecated 43 | # https://github.com/sphinx-doc/sphinx/issues/13083 44 | PYTHONWARNINGS: error,default::DeprecationWarning,default:'sphinx.util.import_object' 45 | run: | 46 | $SPHINX doc/ _build/html/ 47 | -------------------------------------------------------------------------------- /.github/workflows/linkcheck.yml: -------------------------------------------------------------------------------- 1 | name: Check links in documentation 2 | on: [push, pull_request] 3 | env: 4 | PYTHONWARNINGS: error 5 | APT_INSTALL: sudo apt-get install -y --no-install-recommends 6 | PIP: python -m pip 7 | SPHINX: python -m sphinx -W --keep-going --color 8 | jobs: 9 | linkcheck: 10 | runs-on: ubuntu-latest 11 | steps: 12 | - name: Clone repo 13 | uses: actions/checkout@v4 14 | with: 15 | fetch-depth: 0 16 | - name: Install pandoc 17 | run: | 18 | $APT_INSTALL pandoc 19 | - name: Set up Python 20 | uses: actions/setup-python@v5 21 | with: 22 | python-version: "3" 23 | - name: Show Python version 24 | run: | 25 | python --version 26 | - name: Install Python package 27 | env: 28 | # DeprecationWarning: Unimplemented abstract methods {'locate_file'} 29 | # https://github.com/pypa/pip/issues/11684 30 | PYTHONWARNINGS: error,default::DeprecationWarning 31 | run: | 32 | $PIP install . 33 | - name: Install docs dependencies 34 | env: 35 | # DeprecationWarning: Unimplemented abstract methods {'locate_file'} 36 | # https://github.com/pypa/pip/issues/11684 37 | PYTHONWARNINGS: error,default::DeprecationWarning 38 | run: | 39 | $PIP install -r doc/requirements.txt 40 | - name: Check links 41 | env: 42 | # There is a weird warning from jupyter_core (https://github.com/jupyter/jupyter_core/issues/398) 43 | # RemovedInSphinx10Warning: 'sphinx.util.import_object' is deprecated 44 | # https://github.com/sphinx-doc/sphinx/issues/13083 45 | PYTHONWARNINGS: error,default::DeprecationWarning,default:'sphinx.util.import_object' 46 | run: | 47 | $SPHINX -d _doctrees/ doc/ _build/linkcheck/ -b linkcheck -q 48 | - name: Upload results 49 | uses: actions/upload-artifact@v4 50 | if: ${{ success() || failure() }} 51 | with: 52 | name: linkcheck 53 | path: _build/linkcheck/output.* 54 | -------------------------------------------------------------------------------- /.github/workflows/publish.yml: -------------------------------------------------------------------------------- 1 | name: Build and publish to PyPI 2 | on: push 3 | jobs: 4 | build: 5 | name: Build distribution 6 | runs-on: ubuntu-latest 7 | steps: 8 | - uses: actions/checkout@v4 9 | - name: Set up Python 10 | uses: actions/setup-python@v5 11 | with: 12 | python-version: "3" 13 | - name: Install "build" 14 | run: | 15 | python -m pip install build 16 | - name: Build a binary wheel and a source tarball 17 | run: python -m build 18 | - name: Store the distribution packages 19 | uses: actions/upload-artifact@v4 20 | with: 21 | name: dist 22 | path: dist 23 | publish: 24 | name: Upload release to PyPI 25 | if: startsWith(github.ref, 'refs/tags/') 26 | needs: 27 | - build 28 | runs-on: ubuntu-latest 29 | environment: 30 | name: pypi 31 | url: https://pypi.org/p/nbsphinx 32 | permissions: 33 | id-token: write 34 | steps: 35 | - name: Get the artifacts 36 | uses: actions/download-artifact@v4 37 | with: 38 | name: dist 39 | path: dist 40 | - name: Publish package distributions to PyPI 41 | uses: pypa/gh-action-pypi-publish@release/v1 42 | with: 43 | print-hash: true 44 | -------------------------------------------------------------------------------- /.github/workflows/version-matrix.yml: -------------------------------------------------------------------------------- 1 | name: Check different Sphinx and Python versions 2 | on: [push, pull_request] 3 | env: 4 | PYTHONWARNINGS: error 5 | APT_INSTALL: sudo apt-get install -y --no-install-recommends 6 | PIP: python -m pip 7 | SPHINX: python -m sphinx -W --keep-going --color 8 | SPHINX_PACKAGE: "sphinx" 9 | PYTHON_VERSION: "3" 10 | jobs: 11 | version-matrix: 12 | runs-on: ubuntu-latest 13 | strategy: 14 | fail-fast: false 15 | matrix: 16 | include: 17 | 18 | # default Python, latest Sphinx 19 | - env: {} 20 | 21 | # a few older Sphinx releases using default Python version 22 | # sphinx 5.0 and 5.3 requires the imghdr module removed 23 | # in python 3.13 so test with 3.12 24 | - env: 25 | SPHINX_PACKAGE: "sphinx==5.0.0 sphinxcontrib-bibtex==2.5.0" 26 | PYTHON_VERSION: "3.12" 27 | - env: 28 | SPHINX_PACKAGE: "sphinx==5.3.0 sphinxcontrib-bibtex==2.5.0" 29 | PYTHON_VERSION: "3.12" 30 | - env: 31 | SPHINX_PACKAGE: "sphinx==6.2.1 sphinxcontrib-bibtex==2.5.0" 32 | - env: 33 | SPHINX_PACKAGE: "sphinx==7.0.1" 34 | - env: 35 | SPHINX_PACKAGE: "sphinx==7.1.2" 36 | 37 | # a few Python versions using latest Sphinx release 38 | - env: 39 | PYTHON_VERSION: "3.10" 40 | - env: 41 | PYTHON_VERSION: "3.11" 42 | - env: 43 | PYTHON_VERSION: "3.13" 44 | 45 | env: ${{ matrix.env || fromJSON('{}') }} 46 | steps: 47 | - name: Clone repo 48 | uses: actions/checkout@v4 49 | with: 50 | fetch-depth: 0 51 | - name: Install apt packages 52 | run: | 53 | $APT_INSTALL pandoc librsvg2-bin 54 | - name: Set up Python ${{ env.PYTHON_VERSION }} 55 | uses: actions/setup-python@v5 56 | with: 57 | python-version: ${{ env.PYTHON_VERSION }} 58 | - name: Show Python version 59 | run: | 60 | python --version 61 | - name: Install Sphinx 62 | env: 63 | # DeprecationWarning: Unimplemented abstract methods {'locate_file'} 64 | # https://github.com/pypa/pip/issues/11684 65 | PYTHONWARNINGS: error,default::DeprecationWarning 66 | run: | 67 | $PIP install $SPHINX_PACKAGE 68 | - name: Install nbsphinx 69 | env: 70 | # DeprecationWarning: Unimplemented abstract methods {'locate_file'} 71 | # https://github.com/pypa/pip/issues/11684 72 | PYTHONWARNINGS: error,default::DeprecationWarning 73 | run: | 74 | $PIP install . 75 | - name: Install docs dependencies 76 | env: 77 | # DeprecationWarning: Unimplemented abstract methods {'locate_file'} 78 | # https://github.com/pypa/pip/issues/11684 79 | PYTHONWARNINGS: error,default::DeprecationWarning 80 | run: | 81 | $PIP install -r doc/requirements.txt --upgrade-strategy only-if-needed 82 | - name: Run Sphinx (HTML) 83 | env: 84 | # There is a weird warning from jupyter_core (https://github.com/jupyter/jupyter_core/issues/398) 85 | # RemovedInSphinx10Warning: 'sphinx.util.import_object' is deprecated 86 | # https://github.com/sphinx-doc/sphinx/issues/13083 87 | PYTHONWARNINGS: error,default::DeprecationWarning,default:'sphinx.util.import_object' 88 | run: | 89 | $SPHINX doc _build -b html 90 | - name: Run Sphinx (LaTeX, but without running LaTeX) 91 | env: 92 | # There is a weird warning from jupyter_core (https://github.com/jupyter/jupyter_core/issues/398) 93 | # RemovedInSphinx10Warning: 'sphinx.util.import_object' is deprecated 94 | # https://github.com/sphinx-doc/sphinx/issues/13083 95 | PYTHONWARNINGS: error,default::DeprecationWarning,default:'sphinx.util.import_object' 96 | run: | 97 | $SPHINX doc _build -b latex 98 | - name: Run Sphinx (epub) 99 | env: 100 | # There is a weird warning from jupyter_core (https://github.com/jupyter/jupyter_core/issues/398) 101 | # RemovedInSphinx10Warning: 'sphinx.util.import_object' is deprecated 102 | # https://github.com/sphinx-doc/sphinx/issues/13083 103 | PYTHONWARNINGS: error,default::DeprecationWarning,default:'sphinx.util.import_object' 104 | run: | 105 | $SPHINX doc _build -b epub 106 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.pyc 2 | __pycache__/ 3 | build/ 4 | dist/ 5 | nbsphinx.egg-info/ 6 | .ipynb_checkpoints/ 7 | .python-version 8 | .vscode 9 | doc/_build 10 | doc/gallery/a-local-file.png 11 | /theme_comparison/ 12 | /include-in-latex/_build/ 13 | /include-in-latex/pygmentize.py.tex 14 | /include-in-latex/latexmkrc.tex 15 | -------------------------------------------------------------------------------- /.readthedocs.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | build: 3 | os: ubuntu-22.04 4 | tools: 5 | python: "3" 6 | apt_packages: 7 | # rsvg-convert for SVG -> PDF conversion 8 | # using Sphinx extension sphinxcontrib.rsvgconverter, see 9 | # https://github.com/missinglinkelectronics/sphinxcontrib-svg2pdfconverter 10 | - librsvg2-bin 11 | jobs: 12 | post_checkout: 13 | - git fetch --unshallow || true 14 | python: 15 | install: 16 | - requirements: doc/requirements.txt 17 | - method: pip 18 | path: . 19 | - requirements: doc/fallback_theme.txt 20 | sphinx: 21 | configuration: doc/conf.py 22 | formats: all 23 | -------------------------------------------------------------------------------- /CONTRIBUTING.rst: -------------------------------------------------------------------------------- 1 | Contributing 2 | ============ 3 | 4 | If you find bugs, errors, omissions or other things that need improvement, 5 | please create an issue or a pull request at 6 | https://github.com/spatialaudio/nbsphinx/. 7 | Contributions are always welcome! 8 | 9 | 10 | Development Installation 11 | ------------------------ 12 | 13 | .. _prerequisites: https://nbsphinx.readthedocs.io/installation.html 14 | #nbsphinx-Prerequisites 15 | 16 | Make sure that the necessary prerequisites_ are installed. 17 | Then, instead of ``pip``-installing the latest release from PyPI_, 18 | you should get the newest development version (a.k.a. "master") with Git:: 19 | 20 | git clone https://github.com/spatialaudio/nbsphinx.git 21 | cd nbsphinx 22 | python3 -m pip install -e . 23 | 24 | ... where ``-e`` stands for ``--editable``. 25 | 26 | When installing this way, you can quickly try other Git 27 | branches (in this example the branch is called "another-branch"):: 28 | 29 | git checkout another-branch 30 | 31 | If you want to go back to the "master" branch, use:: 32 | 33 | git checkout master 34 | 35 | To get the latest changes from Github, use:: 36 | 37 | git pull --ff-only 38 | 39 | 40 | Building the Documentation 41 | -------------------------- 42 | 43 | If you make changes to the documentation, you should create the HTML 44 | pages locally using Sphinx and check if they look OK. 45 | 46 | Initially, you might need to install a few packages that are needed to build the 47 | documentation:: 48 | 49 | python3 -m pip install -r doc/requirements.txt 50 | 51 | To (re-)build the HTML files, use:: 52 | 53 | python3 setup.py build_sphinx 54 | 55 | If you want to check the LaTeX output, use:: 56 | 57 | python3 setup.py build_sphinx -b latex 58 | 59 | Again, you'll probably have to use ``python`` instead of ``python3``. 60 | The generated files will be available in the directories ``build/sphinx/html/`` 61 | and ``build/sphinx/latex/``, respectively. 62 | 63 | 64 | Building Themes 65 | --------------- 66 | 67 | The ``nbsphinx`` documentation is available in over 30 different `HTML themes`_, 68 | with each having its own branch ending in ``-theme``. 69 | 70 | To simplify the building and testing of themes, 71 | which is especially needed when changing CSS, 72 | we provide you with command line tool to build all themes 73 | or a user specified subset. 74 | The tool is located at ``theme_comparison.py`` and can be run with:: 75 | 76 | python3 theme_comparison.py 77 | 78 | Before doing that, the required dependencies can be obtained with:: 79 | 80 | python3 theme_comparison.py --requirements 81 | 82 | This will create a list of dependencies in 83 | ``theme_comparison/theme_requirements.txt``. 84 | The dependencies can then be installed with:: 85 | 86 | python3 -m pip install -r theme_comparison/theme_requirements.txt 87 | 88 | If you just want to build a subset of the themes 89 | (e.g. ``alabaster`` and ``sphinx_rtd_theme``), simply run:: 90 | 91 | python3 theme_comparison.py alabaster rtd 92 | 93 | For more information run:: 94 | 95 | python3 theme_comparison.py --help 96 | 97 | .. _PyPI: https://pypi.org/project/nbsphinx/ 98 | .. _`HTML themes`: https://nbsphinx.readthedocs.io/usage.html#HTML-Themes 99 | 100 | 101 | Testing 102 | ------- 103 | 104 | Unfortunately, the currently available automated tests are very limited. 105 | Contributions to improve the testing situation are of course also welcome! 106 | 107 | The ``nbsphinx`` documentation also serves as a test case. 108 | However, the resulting HTML/LaTeX/PDF files have to be inspected manually to 109 | check whether they look as expected. 110 | 111 | Sphinx's warnings can help spot problems, therefore it is recommended to use the 112 | ``-W`` flag to turn Sphinx warnings into errors while testing:: 113 | 114 | python3 setup.py build_sphinx -W 115 | 116 | This flag is also used for continuous integration on Github Actions 117 | (see the files ``.github/workflows/*.yml``) and 118 | CircleCI (see the file ``.circleci/config.yml``). 119 | 120 | Sphinx has a ``linkcheck`` builder that can check whether all URLs used in the 121 | documentation are still valid. 122 | This is also part of the continuous integration setup on CircelCI. 123 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2015-2024 Matthias Geier 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining a copy 4 | of this software and associated documentation files (the "Software"), to deal 5 | in the Software without restriction, including without limitation the rights 6 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 7 | copies of the Software, and to permit persons to whom the Software is 8 | furnished to do so, subject to the following conditions: 9 | 10 | The above copyright notice and this permission notice shall be included in 11 | all copies or substantial portions of the Software. 12 | 13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 14 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 15 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 16 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 17 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 18 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 19 | THE SOFTWARE. 20 | -------------------------------------------------------------------------------- /MANIFEST.in: -------------------------------------------------------------------------------- 1 | include LICENSE 2 | include *.rst 3 | include doc/requirements.txt doc/references.bib 4 | recursive-include doc *.ipynb matplotlibrc *.md *.rst *.py *.txt *.svg *.png 5 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | Jupyter Notebook Tools for Sphinx 2 | ================================= 3 | 4 | ``nbsphinx`` is a Sphinx_ extension that provides a source parser for 5 | ``*.ipynb`` files. 6 | Custom Sphinx directives are used to show `Jupyter Notebook`_ code cells (and of 7 | course their results) in both HTML and LaTeX output. 8 | Un-evaluated notebooks -- i.e. notebooks without stored output cells -- will be 9 | automatically executed during the Sphinx build process. 10 | 11 | Quick Start: 12 | #. Install ``nbsphinx`` 13 | 14 | #. Edit your ``conf.py`` and add ``'nbsphinx'`` to ``extensions``. 15 | 16 | #. Edit your ``index.rst`` and add the names of your ``*.ipynb`` files 17 | to the ``toctree``. 18 | 19 | #. Run Sphinx! 20 | 21 | Online documentation (and example of use): 22 | https://nbsphinx.readthedocs.io/ 23 | 24 | Source code repository (and issue tracker): 25 | https://github.com/spatialaudio/nbsphinx/ 26 | 27 | License: 28 | MIT -- see the file ``LICENSE`` for details. 29 | 30 | .. _Sphinx: https://www.sphinx-doc.org/ 31 | .. _Jupyter Notebook: https://jupyter.org/ 32 | -------------------------------------------------------------------------------- /doc/README: -------------------------------------------------------------------------------- 1 | This folder contains the source files for the documentation. 2 | See ../CONTRIBUTING.rst for how to create the HTML and LaTeX 3 | files from these sources. 4 | 5 | The online documentation is available at https://nbsphinx.readthedocs.io/. 6 | -------------------------------------------------------------------------------- /doc/a-markdown-file.md: -------------------------------------------------------------------------------- 1 | # Using Markdown Files 2 | 3 | Sphinx on its own doesn't know how to handle Markdown files, 4 | but there are extensions that enable their usage as Sphinx source files. 5 | For an example, see the 6 | [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/markdown.html). 7 | 8 | Alternatively, when using `nbsphinx` it is also possible to use Markdown 9 | files via [custom notebook formats](custom-formats.pct.py). 10 | 11 | You only need to install the [jupytext](https://jupytext.readthedocs.io/) 12 | package and add a configuration setting to `conf.py`, 13 | which can be used to select one of 14 | [several Markdown flavors supported by jupytext](https://jupytext.readthedocs.io/en/latest/formats-markdown.html) 15 | (here we are using R Markdown): 16 | 17 | ```python 18 | nbsphinx_custom_formats = { 19 | '.md': ['jupytext.reads', {'fmt': 'Rmd'}], 20 | } 21 | ``` 22 | 23 | This very page was generated from a Markdown file using these settings. 24 | 25 | 26 | ## Links to Notebooks (and Other Sphinx Source Files) 27 | 28 | Links to other Sphinx source files can be created like in 29 | [Markdown cells of notebooks](markdown-cells.ipynb#Links-to-Other-Notebooks). 30 | 31 | 32 | ## Math 33 | 34 | Mathematical equations can be used just like in 35 | [Markdown cells of notebooks](markdown-cells.ipynb#Equations). 36 | 37 | Inline like this: $\text{e}^{i\pi} = -1$. 38 | 39 | Or as a separate block: 40 | 41 | \begin{equation*} 42 | \int\limits_{-\infty}^\infty f(x) \delta(x - x_0) dx = f(x_0) 43 | \end{equation*} 44 | 45 | 46 | ## Tables 47 | 48 | A | B | A and B 49 | ------|-------|-------- 50 | False | False | False 51 | True | False | False 52 | False | True | False 53 | True | True | True 54 | 55 | 56 | ## Images 57 | 58 | ![Jupyter notebook icon](images/notebook_icon.png) 59 | -------------------------------------------------------------------------------- /doc/a-normal-rst-file.rst: -------------------------------------------------------------------------------- 1 | Normal reStructuredText Files 2 | ============================= 3 | 4 | This is a normal RST file. 5 | 6 | .. note:: Those still work! 7 | 8 | Links to Notebooks (and Other Sphinx Source Files) 9 | -------------------------------------------------- 10 | 11 | Links to Sphinx source files can be created like normal `Sphinx hyperlinks`_, 12 | just using a relative path to the local file: link_. 13 | 14 | .. _Sphinx hyperlinks: https://www.sphinx-doc.org/en/master/usage/ 15 | restructuredtext/basics.html#external-links 16 | .. _link: subdir/a-notebook-in-a-subdir.ipynb 17 | 18 | .. code-block:: rst 19 | 20 | using a relative path to the local file: link_. 21 | 22 | .. _link: subdir/a-notebook-in-a-subdir.ipynb 23 | 24 | If the link text has a space (or some other strange character) in it, you have 25 | to surround it with backticks: `a notebook link`_. 26 | 27 | .. _a notebook link: subdir/a-notebook-in-a-subdir.ipynb 28 | 29 | .. code-block:: rst 30 | 31 | surround it with backticks: `a notebook link`_. 32 | 33 | .. _a notebook link: subdir/a-notebook-in-a-subdir.ipynb 34 | 35 | You can also use an `anonymous hyperlink target`_, like this: link__. 36 | If you have multiple of those, their order matters! 37 | 38 | .. _anonymous hyperlink target: https://docutils.sourceforge.io/docs/ref/rst/ 39 | restructuredtext.html#anonymous-hyperlinks 40 | 41 | __ subdir/a-notebook-in-a-subdir.ipynb 42 | 43 | .. code-block:: rst 44 | 45 | like this: link__. 46 | 47 | __ subdir/a-notebook-in-a-subdir.ipynb 48 | 49 | Finally, you can use `Embedded URIs`_, like this 50 | `link `_. 51 | 52 | .. _Embedded URIs: https://docutils.sourceforge.io/docs/ref/rst/ 53 | restructuredtext.html#embedded-uris-and-aliases 54 | 55 | .. code-block:: rst 56 | 57 | like this `link `_. 58 | 59 | .. note:: 60 | 61 | These links should also work on Github and in other rendered 62 | reStructuredText pages. 63 | 64 | Links to subsections are also possible by adding a hash sign (``#``) and the 65 | section title to any of the above-mentioned link variants. 66 | You have to replace spaces in the section titles by hyphens. 67 | For example, see this subsection_. 68 | 69 | .. _subsection: subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section 70 | 71 | .. code-block:: rst 72 | 73 | For example, see this subsection_. 74 | 75 | .. _subsection: subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section 76 | 77 | 78 | Links to Notebooks, Ye Olde Way 79 | ------------------------------- 80 | 81 | In addition to the way shown above, you can also create links to notebooks (and 82 | other Sphinx source files) with 83 | `:ref: `_. 84 | This has some disadvantages: 85 | 86 | * It is arguably a bit more clunky. 87 | * Because ``:ref:`` is a Sphinx feature, the links don't work on Github and 88 | other rendered reStructuredText pages that use plain old ``docutils``. 89 | 90 | It also has one important advantage: 91 | 92 | * The link text can automatically be taken from the actual section title. 93 | 94 | A link with automatic title looks like this: 95 | :ref:`/subdir/a-notebook-in-a-subdir.ipynb`. 96 | 97 | .. code-block:: rst 98 | 99 | :ref:`/subdir/a-notebook-in-a-subdir.ipynb` 100 | 101 | But you can also provide 102 | :ref:`your own link title `. 103 | 104 | .. code-block:: rst 105 | 106 | :ref:`your own link title ` 107 | 108 | However, if you want to use your own title, you are probably better off using 109 | the method described above in 110 | `Links to Notebooks (and Other Sphinx Source Files)`_. 111 | 112 | Links to subsections are also possible, e.g. 113 | :ref:`/subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section` 114 | (the subsection title is used as link text) and 115 | :ref:`alternative text `. 116 | 117 | These links were created with: 118 | 119 | .. code-block:: rst 120 | 121 | :ref:`/subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section` 122 | :ref:`alternative text ` 123 | 124 | .. note:: 125 | 126 | * The paths have to be relative to the top source directory and they have to 127 | start with a slash (``/``). 128 | * Spaces in the section title have to be replaced by hyphens! 129 | 130 | Sphinx Directives for Info/Warning Boxes 131 | ---------------------------------------- 132 | 133 | .. nbwarning:: 134 | Warning 135 | 136 | This is an experimental feature! 137 | Its usage may change in the future or it might disappear completely, so 138 | don't use it for now. 139 | 140 | With a bit of luck, it will be possible (some time in the future) to create 141 | info/warning boxes in Markdown cells, see 142 | https://github.com/jupyter/notebook/issues/1292. 143 | If this ever happens, ``nbsphinx`` will provide directives for creating such 144 | boxes. 145 | For now, there are two directives available: ``nbinfo`` and ``nbwarning``. 146 | This is how an info box looks like: 147 | 148 | .. nbinfo:: 149 | Note 150 | 151 | This is an info box. 152 | 153 | It may include nested formatting, even another info/warning box: 154 | 155 | .. nbwarning:: **Warning:** You should probably not use nested boxes! 156 | 157 | Domain Objects 158 | -------------- 159 | 160 | .. py:function:: example_python_function(foo) 161 | 162 | This is just for testing domain object links. 163 | 164 | :param str foo: Example string parameter 165 | 166 | .. seealso:: 167 | 168 | :ref:`/markdown-cells.ipynb#Links-to-Domain-Objects` 169 | 170 | 171 | References 172 | ---------- 173 | 174 | There are different ways of handling references, for example you could use the 175 | `standard Sphinx citations`_, but it might be more practical to use the 176 | sphinxcontrib.bibtex_ extension. 177 | 178 | After installing the sphinxcontrib.bibtex_ extension, you have to enable it in 179 | your ``conf.py`` and select the BibTeX file(s) you want to use: 180 | 181 | .. code-block:: python 182 | 183 | extensions = [ 184 | 'nbsphinx', 185 | 'sphinxcontrib.bibtex', 186 | # Probably more extensions here ... 187 | ] 188 | 189 | bibtex_bibfiles = ['my-references.bib'] 190 | bibtex_reference_style = 'author_year' 191 | 192 | Afterwards all the references defined in the bibliography file(s) can be used 193 | throughout the Jupyter notebooks and other source files as detailed in the following. 194 | 195 | .. _standard Sphinx Citations: https://www.sphinx-doc.org/en/master/usage/ 196 | restructuredtext/basics.html#citations 197 | .. _sphinxcontrib.bibtex: https://sphinxcontrib-bibtex.readthedocs.io/ 198 | 199 | Citations 200 | ^^^^^^^^^ 201 | 202 | You can create citations like :cite:`perez2011python`: 203 | 204 | .. code-block:: rst 205 | 206 | :cite:`perez2011python` 207 | 208 | You can also create so-called in-text citations, 209 | where the names of the authors, for example :cite:t:`perez2011python`, 210 | are part of the sentence: 211 | 212 | .. code-block:: rst 213 | 214 | :cite:t:`perez2011python` 215 | 216 | You can create similar citations in Jupyter notebooks with a special HTML 217 | syntax, see the section about 218 | `citations in Markdown cells `__. 219 | 220 | You can create a list of references in any reStructuredText file 221 | (or `reST cell `_ in a notebook) like this: 222 | 223 | .. code-block:: rst 224 | 225 | .. bibliography:: 226 | 227 | For an example, see the file ``doc/references.rst``. 228 | 229 | 230 | Footnote citations 231 | ^^^^^^^^^^^^^^^^^^ 232 | 233 | With a sphinxcontrib.bibtex_ version of ``>= 2.0.0`` it is 234 | possible to create footnote bibliographies with footnote 235 | citations like :footcite:`perez2011python`. 236 | 237 | .. code-block:: rst 238 | 239 | :footcite:`perez2011python` 240 | 241 | In-text citations like :footcite:t:`kluyver2016jupyter` can be created like this: 242 | 243 | .. code-block:: rst 244 | 245 | :footcite:t:`kluyver2016jupyter` 246 | 247 | Also footnote citations can be used within Jupyter notebooks with a special HTML syntax, 248 | see the section about 249 | `footnote citations in Markdown cells `__. 250 | Footnote citations are restricted to their own source file and the assembly of the 251 | bibliography is (analogously to normal citations) invoked with the 252 | 253 | .. code-block:: rst 254 | 255 | .. footbibliography:: 256 | 257 | directive. For example, a footnote bibliography might 258 | look like this (in HTML output): 259 | 260 | .. footbibliography:: 261 | 262 | In the LaTeX/PDF output, there is no list of references appearing right 263 | here. Instead, the footnote citations are placed into the footnotes of 264 | their respective pages. 265 | 266 | 267 | Thumbnail Link Galleries (HTML only) 268 | ------------------------------------- 269 | 270 | In some case it is desired to create thumbnail links to existing notebooks, 271 | already included in a ``toctree``. This can be used e.g. to link to a subset 272 | of notebooks from API documentation to highlight the use of some functionality. 273 | For this there is a dedicated ``nblinkgallery`` directive. 274 | 275 | The following example gallery was created using: 276 | 277 | .. code-block:: rest 278 | 279 | .. nblinkgallery:: 280 | :caption: A few links 281 | :name: rst-link-gallery 282 | 283 | gallery/multiple-outputs 284 | gallery/no-thumbnail 285 | gallery/cell-metadata 286 | orphan 287 | 288 | .. nblinkgallery:: 289 | :caption: A few links 290 | :name: rst-link-gallery 291 | 292 | gallery/multiple-outputs 293 | gallery/no-thumbnail 294 | gallery/cell-metadata 295 | orphan 296 | 297 | .. seealso:: 298 | 299 | `Link Galleries in Jupyter Notebooks `_ 300 | 301 | 302 | Thumbnail Galleries 303 | ------------------- 304 | 305 | With ``nbsphinx`` you can create thumbnail galleries in notebook files 306 | as described in :ref:`/gallery/gallery-with-nested-documents.ipynb`. 307 | If you like, you can also create such galleries in reST files 308 | using the ``nbgallery`` directive. 309 | It takes the same parameters as the `toctree`__ directive. 310 | 311 | __ https://www.sphinx-doc.org/en/master/usage/restructuredtext/ 312 | directives.html#directive-toctree 313 | 314 | .. note:: 315 | 316 | The notes regarding LaTeX in :ref:`/gallery/gallery-with-nested-documents.ipynb` 317 | and :ref:`/subdir/toctree.ipynb` also apply here! 318 | 319 | The following example gallery was created using: 320 | 321 | .. code-block:: rest 322 | 323 | .. nbgallery:: 324 | :caption: This is a thumbnail gallery: 325 | :name: rst-gallery 326 | :glob: 327 | :reversed: 328 | 329 | gallery/*-rst 330 | 331 | .. nbgallery:: 332 | :caption: This is a thumbnail gallery: 333 | :name: rst-gallery 334 | :glob: 335 | :reversed: 336 | 337 | gallery/*-rst 338 | -------------------------------------------------------------------------------- /doc/allow-errors-per-cell.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: http://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Ignoring Errors on a Per-Cell Basis\n", 17 | "\n", 18 | "Instead of ignoring errors for all notebooks or for some selected notebooks (see [the previous notebook](allow-errors.ipynb)), you can be more fine-grained and just allow errors on certain code cells by tagging them with the `raises-exception` tag." 19 | ] 20 | }, 21 | { 22 | "cell_type": "code", 23 | "execution_count": null, 24 | "metadata": {}, 25 | "outputs": [], 26 | "source": [ 27 | "'no problem'" 28 | ] 29 | }, 30 | { 31 | "cell_type": "markdown", 32 | "metadata": {}, 33 | "source": [ 34 | "The following code cell has the `raises-exception` tag." 35 | ] 36 | }, 37 | { 38 | "cell_type": "code", 39 | "execution_count": null, 40 | "metadata": { 41 | "tags": [ 42 | "raises-exception" 43 | ] 44 | }, 45 | "outputs": [], 46 | "source": [ 47 | "problem" 48 | ] 49 | }, 50 | { 51 | "cell_type": "markdown", 52 | "metadata": {}, 53 | "source": [ 54 | "The following code cell is executed even though the previous cell raised an exception." 55 | ] 56 | }, 57 | { 58 | "cell_type": "code", 59 | "execution_count": null, 60 | "metadata": {}, 61 | "outputs": [], 62 | "source": [ 63 | "'no problem'" 64 | ] 65 | }, 66 | { 67 | "cell_type": "markdown", 68 | "metadata": {}, 69 | "source": [ 70 | "
\n", 71 | "\n", 72 | "Note\n", 73 | "\n", 74 | "The behavior of the `raises-exception` tag doesn't match its name.\n", 75 | "While it does *allow* exceptions,\n", 76 | "it does not check if an exception is actually raised!\n", 77 | "\n", 78 | "This will hopefully be fixed at some point,\n", 79 | "see https://github.com/jupyter/nbconvert/issues/730.\n", 80 | "\n", 81 | "
" 82 | ] 83 | } 84 | ], 85 | "metadata": { 86 | "celltoolbar": "Tags", 87 | "kernelspec": { 88 | "display_name": "Python 3", 89 | "language": "python", 90 | "name": "python3" 91 | }, 92 | "language_info": { 93 | "codemirror_mode": { 94 | "name": "ipython", 95 | "version": 3 96 | }, 97 | "file_extension": ".py", 98 | "mimetype": "text/x-python", 99 | "name": "python", 100 | "nbconvert_exporter": "python", 101 | "pygments_lexer": "ipython3", 102 | "version": "3.7.4+" 103 | } 104 | }, 105 | "nbformat": 4, 106 | "nbformat_minor": 4 107 | } 108 | -------------------------------------------------------------------------------- /doc/allow-errors.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Ignoring Errors\n", 17 | "\n", 18 | "Normally, if an exception is raised while executing a notebook, the Sphinx build process is stopped immediately.\n", 19 | "\n", 20 | "If a notebook contains errors on purpose (or if you are too lazy to fix them right now), you have four options:\n", 21 | "\n", 22 | "1. Manually execute the notebook in question and save the results, see [the pre-executed example notebook](pre-executed.ipynb).\n", 23 | "\n", 24 | "2. Allow errors in all notebooks by setting this option\n", 25 | " in [conf.py](conf.py):\n", 26 | "\n", 27 | " ```python\n", 28 | " nbsphinx_allow_errors = True\n", 29 | " ```\n", 30 | "\n", 31 | "3. Allow errors on a per-notebook basis by adding this to the notebook's\n", 32 | " JSON metadata:\n", 33 | "\n", 34 | " ```\n", 35 | " \"nbsphinx\": {\n", 36 | " \"allow_errors\": true\n", 37 | " },\n", 38 | " ```\n", 39 | "\n", 40 | "4. Allow errors on a per-cell basis using the `raises-exception` tag, see [Ignoring Errors on a Cell-by-Cell Basis](allow-errors-per-cell.ipynb).\n", 41 | "\n", 42 | "This very notebook is an example for the third option.\n", 43 | "The results of the following code cells are not stored within the notebook, therefore it is executed during the Sphinx build process.\n", 44 | "Since the above-mentioned `allow_errors` flag is set in this notebook's metadata, all cells are executed although most of them cause an exception." 45 | ] 46 | }, 47 | { 48 | "cell_type": "code", 49 | "execution_count": null, 50 | "metadata": {}, 51 | "outputs": [], 52 | "source": [ 53 | "nonsense" 54 | ] 55 | }, 56 | { 57 | "cell_type": "code", 58 | "execution_count": null, 59 | "metadata": {}, 60 | "outputs": [], 61 | "source": [ 62 | "42 / 0" 63 | ] 64 | }, 65 | { 66 | "cell_type": "code", 67 | "execution_count": null, 68 | "metadata": {}, 69 | "outputs": [], 70 | "source": [ 71 | "6 * 7" 72 | ] 73 | } 74 | ], 75 | "metadata": { 76 | "kernelspec": { 77 | "display_name": "Python 3", 78 | "language": "python", 79 | "name": "python3" 80 | }, 81 | "language_info": { 82 | "codemirror_mode": { 83 | "name": "ipython", 84 | "version": 3 85 | }, 86 | "file_extension": ".py", 87 | "mimetype": "text/x-python", 88 | "name": "python", 89 | "nbconvert_exporter": "python", 90 | "pygments_lexer": "ipython3", 91 | "version": "3.9.7" 92 | }, 93 | "nbsphinx": { 94 | "allow_errors": true 95 | } 96 | }, 97 | "nbformat": 4, 98 | "nbformat_minor": 4 99 | } 100 | -------------------------------------------------------------------------------- /doc/conf.py: -------------------------------------------------------------------------------- 1 | import os 2 | 3 | # You can use sphinx-quickstart to create your own conf.py file! 4 | # After that, you have to edit a few things. See below. 5 | 6 | # Select nbsphinx and, if needed, other Sphinx extensions: 7 | extensions = [ 8 | 'nbsphinx', 9 | 'sphinxcontrib.bibtex', # for bibliographic references 10 | 'sphinxcontrib.rsvgconverter', # for SVG->PDF conversion in LaTeX output 11 | 'sphinx_last_updated_by_git', # get "last updated" from Git 12 | 'sphinx_codeautolink', # automatic links from code to documentation 13 | 'sphinx.ext.intersphinx', # links to other Sphinx projects (e.g. NumPy) 14 | ] 15 | 16 | # These projects are also used for the sphinx_codeautolink extension: 17 | intersphinx_mapping = { 18 | 'IPython': ('https://ipython.readthedocs.io/en/stable/', None), 19 | 'matplotlib': ('https://matplotlib.org/', None), 20 | 'numpy': ('https://docs.scipy.org/doc/numpy/', None), 21 | 'pandas': ('https://pandas.pydata.org/docs/', None), 22 | 'python': ('https://docs.python.org/3/', None), 23 | } 24 | 25 | # Don't add .txt suffix to source files: 26 | html_sourcelink_suffix = '' 27 | 28 | # List of arguments to be passed to the kernel that executes the notebooks: 29 | nbsphinx_execute_arguments = [ 30 | "--InlineBackend.figure_formats={'svg', 'pdf'}", 31 | ] 32 | 33 | # Environment variables to be passed to the kernel: 34 | os.environ['MY_DUMMY_VARIABLE'] = 'Hello from conf.py!' 35 | 36 | nbsphinx_thumbnails = { 37 | 'gallery/thumbnail-from-conf-py': 'gallery/a-local-file.png', 38 | 'gallery/*-rst': 'images/notebook_icon.png', 39 | 'orphan': '_static/favicon.svg', 40 | } 41 | 42 | # This is processed by Jinja2 and inserted before each notebook 43 | nbsphinx_prolog = r""" 44 | {% set docname = 'doc/' + env.doc2path(env.docname, base=None)|string %} 45 | 46 | .. raw:: html 47 | 48 |
49 | This page was generated from 50 | {{ docname|e }}. 51 | Interactive online version: 52 | Binder badge. 53 | Download notebook. 54 | 69 |
70 | 71 | .. raw:: latex 72 | 73 | \nbsphinxstartnotebook{\scriptsize\noindent\strut 74 | \textcolor{gray}{The following section was generated from 75 | \sphinxcode{\sphinxupquote{\strut {{ docname | escape_latex }}}} \dotfill}} 76 | """ 77 | 78 | # This is processed by Jinja2 and inserted after each notebook 79 | nbsphinx_epilog = r""" 80 | {% set docname = 'doc/' + env.doc2path(env.docname, base=None)|string %} 81 | .. raw:: latex 82 | 83 | \nbsphinxstopnotebook{\scriptsize\noindent\strut 84 | \textcolor{gray}{\dotfill\ \sphinxcode{\sphinxupquote{\strut 85 | {{ docname | escape_latex }}}} ends here.}} 86 | """ 87 | 88 | mathjax3_config = { 89 | 'tex': {'tags': 'ams', 'useLabelIds': True}, 90 | } 91 | 92 | # https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html 93 | bibtex_bibfiles = ['references.bib'] 94 | bibtex_reference_style = 'author_year' 95 | 96 | # Support for notebook formats other than .ipynb 97 | nbsphinx_custom_formats = { 98 | '.pct.py': ['jupytext.reads', {'fmt': 'py:percent'}], 99 | '.md': ['jupytext.reads', {'fmt': 'Rmd'}], 100 | } 101 | 102 | # Import Matplotlib to avoid this message in notebooks: 103 | # "Matplotlib is building the font cache; this may take a moment." 104 | import matplotlib.pyplot 105 | 106 | # -- The settings below this line are not specific to nbsphinx ------------ 107 | 108 | master_doc = 'index' 109 | 110 | project = 'nbsphinx' 111 | author = 'Matthias Geier' 112 | copyright = '2020, ' + author 113 | html_show_copyright = False 114 | 115 | linkcheck_ignore = [ 116 | r'http://localhost:\d+/', 117 | 'https://github.com/spatialaudio/nbsphinx/compare/', 118 | # 418 Client Error: Unknown for url: https://ieeexplore.ieee.org/document/5582063/ 119 | 'https://doi.org/10.1109/MCSE.2010.119', 120 | # Intermittent network errors: 121 | # Failed to establish a new connection: [Errno 101] Network is unreachable 122 | 'https://repology.org/', 123 | ] 124 | 125 | nitpicky = True 126 | 127 | # -- Get version information and date from Git ---------------------------- 128 | 129 | try: 130 | from subprocess import check_output 131 | release = check_output(['git', 'describe', '--tags', '--always']) 132 | release = release.decode().strip() 133 | today = check_output(['git', 'show', '-s', '--format=%ad', '--date=short']) 134 | today = today.decode().strip() 135 | except Exception: 136 | release = '' 137 | today = '' 138 | 139 | # -- Options for HTML output ---------------------------------------------- 140 | 141 | html_favicon = 'favicon.svg' 142 | html_title = project + ' version ' + release 143 | 144 | # -- Options for LaTeX output --------------------------------------------- 145 | 146 | # See https://www.sphinx-doc.org/en/master/latex.html 147 | latex_elements = { 148 | 'papersize': 'a4paper', 149 | 'printindex': '', 150 | 'sphinxsetup': r""" 151 | HeaderFamily=\rmfamily\bfseries, 152 | div.note_border-TeXcolor={HTML}{E0E0E0}, 153 | div.note_border-width=0.5pt, 154 | div.note_box-decoration-break=slice, 155 | div.warning_border-TeXcolor={HTML}{E0E0E0}, 156 | div.warning_border-width=1.5pt, 157 | div.warning_background-TeXcolor={HTML}{FBFBFB}, 158 | div.warning_box-decoration-break=slice, 159 | div.topic_box-shadow=none, 160 | div.topic_border-TeXcolor={HTML}{E0E0E0}, 161 | div.topic_border-width=0.5pt, 162 | div.topic_box-decoration-break=slice, 163 | """, 164 | 'fontpkg': r""" 165 | \usepackage{mathpazo} 166 | \linespread{1.05} % see http://www.tug.dk/FontCatalogue/urwpalladio/ 167 | \setmainfont{TeX Gyre Pagella}[Numbers=OldStyle] 168 | \setmonofont{Latin Modern Mono Light}[Numbers=Lining] 169 | """, 170 | 'preamble': r""" 171 | \urlstyle{tt} 172 | """, 173 | } 174 | 175 | latex_engine = 'lualatex' 176 | latex_use_xindy = False 177 | 178 | latex_table_style = ['booktabs'] 179 | 180 | latex_documents = [ 181 | (master_doc, 'nbsphinx.tex', project, author, 'howto'), 182 | ] 183 | 184 | latex_show_urls = 'footnote' 185 | latex_show_pagerefs = True 186 | 187 | # -- Work-around to get LaTeX References at the same place as HTML -------- 188 | 189 | # See https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/156 190 | 191 | import sphinx.builders.latex.transforms 192 | 193 | class DummyTransform(sphinx.builders.latex.transforms.BibliographyTransform): 194 | 195 | def run(self, **kwargs): 196 | pass 197 | 198 | sphinx.builders.latex.transforms.BibliographyTransform = DummyTransform 199 | 200 | # -- Options for EPUB output ---------------------------------------------- 201 | 202 | # These are just defined to avoid Sphinx warnings related to EPUB: 203 | version = release 204 | suppress_warnings = ['epub.unknown_project_files'] 205 | 206 | # -- Set default HTML theme (if none was given above) --------------------- 207 | 208 | if 'html_theme' not in globals(): 209 | try: 210 | import insipid_sphinx_theme 211 | except ImportError: 212 | pass 213 | else: 214 | html_theme = 'insipid' 215 | html_copy_source = False 216 | html_permalinks_icon = '#' 217 | 218 | if globals().get('html_theme') == 'insipid': 219 | # This controls optional content in index.rst: 220 | tags.add('insipid') 221 | -------------------------------------------------------------------------------- /doc/configuration.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Configuration\n", 17 | "\n", 18 | "The following configuration values\n", 19 | "can be used in the `conf.py` file,\n", 20 | "see [Project Setup](usage.ipynb#Project-Setup)." 21 | ] 22 | }, 23 | { 24 | "cell_type": "markdown", 25 | "metadata": {}, 26 | "source": [ 27 | "## Sphinx Configuration Values\n", 28 | "\n", 29 | "All configuration values are described in the\n", 30 | "[Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/configuration.html),\n", 31 | "here we mention only the ones which may be relevant\n", 32 | "in combination with `nbsphinx`." 33 | ] 34 | }, 35 | { 36 | "cell_type": "markdown", 37 | "metadata": {}, 38 | "source": [ 39 | "#### `exclude_patterns`\n", 40 | "\n", 41 | "Sphinx builds all potential source files (reST files, Jupyter notebooks, ...)\n", 42 | "that are in the source directory (including any sub-directories),\n", 43 | "whether you want to use them or not.\n", 44 | "If you want certain source files not to be built,\n", 45 | "specify them in\n", 46 | "[exclude_patterns](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-exclude_patterns).\n", 47 | "For example, you might want to ignore source files in your build directory:\n", 48 | "\n", 49 | "```python\n", 50 | "exclude_patterns = ['_build']\n", 51 | "```\n", 52 | "\n", 53 | "Note that the directory `.ipynb_checkpoints`\n", 54 | "is automatically added\n", 55 | "to `exclude_patterns`\n", 56 | "by `nbsphinx`." 57 | ] 58 | }, 59 | { 60 | "cell_type": "markdown", 61 | "metadata": {}, 62 | "source": [ 63 | "#### `extensions`\n", 64 | "\n", 65 | "This is the only required value.\n", 66 | "You have to add `'nbsphinx'` to the list of\n", 67 | "[extensions](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-extensions),\n", 68 | "otherwise it won't work.\n", 69 | "\n", 70 | "Other interesting extensions are:\n", 71 | "\n", 72 | "* `'sphinx.ext.mathjax'` (Sphinx loads this by default)\n", 73 | " for [math formulas](markdown-cells.ipynb#Equations)\n", 74 | "* `'sphinxcontrib.bibtex'`\n", 75 | " for [bibliographic references](a-normal-rst-file.rst#references)\n", 76 | "* `'sphinxcontrib.rsvgconverter'`\n", 77 | " for [SVG->PDF conversion in LaTeX output](markdown-cells.ipynb#SVG-support-for-LaTeX)\n", 78 | "* `'sphinx_copybutton'`\n", 79 | " for [adding \"copy to clipboard\" buttons](https://sphinx-copybutton.readthedocs.io/)\n", 80 | " to all text/code boxes" 81 | ] 82 | }, 83 | { 84 | "cell_type": "markdown", 85 | "metadata": {}, 86 | "source": [ 87 | "#### `html_css_files`\n", 88 | "\n", 89 | "See [Custom CSS](custom-css.ipynb) and\n", 90 | "[html_css_files](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files)." 91 | ] 92 | }, 93 | { 94 | "cell_type": "markdown", 95 | "metadata": {}, 96 | "source": [ 97 | "#### `html_sourcelink_suffix`\n", 98 | "\n", 99 | "\n", 100 | "By default, a `.txt` suffix is added to source files.\n", 101 | "This is only relevant if the chosen HTML theme supports source links and if\n", 102 | "[html_show_sourcelink](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_show_sourcelink)\n", 103 | "is `True`.\n", 104 | "\n", 105 | "Jupyter notebooks with the suffix `.ipynb.txt` are normally not very useful,\n", 106 | "so if you want to avoid the additional suffix, set\n", 107 | "[html_sourcelink_suffix](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sourcelink_suffix) to the empty string:\n", 108 | "\n", 109 | "```python\n", 110 | "html_sourcelink_suffix = ''\n", 111 | "```" 112 | ] 113 | }, 114 | { 115 | "cell_type": "markdown", 116 | "metadata": {}, 117 | "source": [ 118 | "#### `latex_additional_files`\n", 119 | "\n", 120 | "[latex_additional_files](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-latex_additional_files)\n", 121 | "can be useful if you are using BibTeX files, see\n", 122 | "[References](a-normal-rst-file.rst#references)." 123 | ] 124 | }, 125 | { 126 | "cell_type": "markdown", 127 | "metadata": {}, 128 | "source": [ 129 | "#### `mathjax3_config`\n", 130 | "\n", 131 | "The configuration value\n", 132 | "[mathjax3_config](https://www.sphinx-doc.org/en/master/usage/extensions/math.html#confval-mathjax3_config)\n", 133 | "can be useful to enable\n", 134 | "[Automatic Equation Numbering](markdown-cells.ipynb#Automatic-Equation-Numbering).\n", 135 | "\n", 136 | "For Sphinx versions below 4.0.0, which used MathJax version 2,\n", 137 | "the relevant configuration value was called `mathjax_config`." 138 | ] 139 | }, 140 | { 141 | "cell_type": "markdown", 142 | "metadata": {}, 143 | "source": [ 144 | "#### `pygments_style`\n", 145 | "\n", 146 | "Use\n", 147 | "[pygments_style](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-pygments_style)\n", 148 | "to change the color/font theme that's used for syntax highlighting in source code.\n", 149 | "\n", 150 | "This affects both [code cells](code-cells.ipynb)\n", 151 | "and [code blocks in Markdown cells](markdown-cells.ipynb#Code)\n", 152 | "(unless overwritten by the\n", 153 | "[html_theme](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_theme))." 154 | ] 155 | }, 156 | { 157 | "cell_type": "markdown", 158 | "metadata": {}, 159 | "source": [ 160 | "#### `suppress_warnings`\n", 161 | "\n", 162 | "Warnings can be really helpful to detect small mistakes,\n", 163 | "and you should consider invoking Sphinx with the\n", 164 | "[-W](https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-W)\n", 165 | "option,\n", 166 | "which turns warnings into errors.\n", 167 | "However, warnings can also be annoying,\n", 168 | "especially if you are fully aware of the \"problem\",\n", 169 | "but you simply don't care about it for some reason.\n", 170 | "In this case, you can use\n", 171 | "[suppress_warnings](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-suppress_warnings)\n", 172 | "to silence specific types of warnings.\n", 173 | "\n", 174 | "If you want to suppress all warnings from `nbsphinx`, use this:\n", 175 | "\n", 176 | "```python\n", 177 | "suppress_warnings = [\n", 178 | " 'nbsphinx',\n", 179 | "]\n", 180 | "```\n", 181 | "\n", 182 | "You can also be more specific:\n", 183 | "\n", 184 | "```python\n", 185 | "suppress_warnings = [\n", 186 | " 'nbsphinx.localfile',\n", 187 | " 'nbsphinx.gallery',\n", 188 | " 'nbsphinx.thumbnail',\n", 189 | " 'nbsphinx.notebooktitle',\n", 190 | " 'nbsphinx.ipywidgets',\n", 191 | "]\n", 192 | "```" 193 | ] 194 | }, 195 | { 196 | "cell_type": "markdown", 197 | "metadata": {}, 198 | "source": [ 199 | "## `nbsphinx` Configuration Values" 200 | ] 201 | }, 202 | { 203 | "cell_type": "markdown", 204 | "metadata": {}, 205 | "source": [ 206 | "#### `nbsphinx_allow_errors`\n", 207 | "\n", 208 | "If `True`, the build process is continued even if an exception occurs.\n", 209 | "\n", 210 | "See [Ignoring Errors](allow-errors.ipynb)." 211 | ] 212 | }, 213 | { 214 | "cell_type": "markdown", 215 | "metadata": {}, 216 | "source": [ 217 | "#### `nbsphinx_assume_equations`\n", 218 | "\n", 219 | "If `False`, do not force loading MathJax on HTML pages generated from notebooks." 220 | ] 221 | }, 222 | { 223 | "cell_type": "markdown", 224 | "metadata": {}, 225 | "source": [ 226 | "#### `nbsphinx_codecell_lexer`\n", 227 | "\n", 228 | "Default Pygments lexer for syntax highlighting in code cells.\n", 229 | "If available,\n", 230 | "this information is taken from the notebook metadata instead." 231 | ] 232 | }, 233 | { 234 | "cell_type": "markdown", 235 | "metadata": {}, 236 | "source": [ 237 | "#### `nbsphinx_custom_formats`\n", 238 | "\n", 239 | "See [Custom Notebook Formats](custom-formats.ipynb)." 240 | ] 241 | }, 242 | { 243 | "cell_type": "markdown", 244 | "metadata": {}, 245 | "source": [ 246 | "#### `nbsphinx_epilog`\n", 247 | "\n", 248 | "See [Prolog and Epilog](prolog-and-epilog.ipynb)." 249 | ] 250 | }, 251 | { 252 | "cell_type": "markdown", 253 | "metadata": {}, 254 | "source": [ 255 | "#### `nbsphinx_execute`\n", 256 | "\n", 257 | "Whether to execute notebooks before conversion or not.\n", 258 | "Possible values: `'always'`, `'never'`, `'auto'` (default).\n", 259 | "\n", 260 | "See [Explicitly Dis-/Enabling Notebook Execution](never-execute.ipynb)." 261 | ] 262 | }, 263 | { 264 | "cell_type": "markdown", 265 | "metadata": {}, 266 | "source": [ 267 | "#### `nbsphinx_execute_arguments`\n", 268 | "\n", 269 | "Kernel arguments used when executing notebooks.\n", 270 | "\n", 271 | "See [Configuring the Kernels](configuring-kernels.ipynb#Kernel-Arguments)." 272 | ] 273 | }, 274 | { 275 | "cell_type": "markdown", 276 | "metadata": {}, 277 | "source": [ 278 | "#### `nbsphinx_input_prompt`\n", 279 | "\n", 280 | "Input prompt for code cells. `%s` is replaced by the execution count.\n", 281 | "\n", 282 | "To get a prompt similar to the Classic Notebook, use\n", 283 | "\n", 284 | "```python\n", 285 | "nbsphinx_input_prompt = 'In [%s]:'\n", 286 | "```" 287 | ] 288 | }, 289 | { 290 | "cell_type": "markdown", 291 | "metadata": {}, 292 | "source": [ 293 | "#### `nbsphinx_kernel_name`\n", 294 | "\n", 295 | "Use a different kernel than stored in the notebook metadata, e.g.:\n", 296 | "\n", 297 | "```python\n", 298 | "nbsphinx_kernel_name = 'python3'\n", 299 | "```\n", 300 | "\n", 301 | "See [Configuring the Kernels](configuring-kernels.ipynb#Kernel-Name)." 302 | ] 303 | }, 304 | { 305 | "cell_type": "markdown", 306 | "metadata": {}, 307 | "source": [ 308 | "#### `nbsphinx_output_prompt`\n", 309 | "\n", 310 | "Output prompt for code cells. `%s` is replaced by the execution count.\n", 311 | "\n", 312 | "To get a prompt similar to the Classic Notebook, use\n", 313 | "\n", 314 | "```python\n", 315 | "nbsphinx_output_prompt = 'Out[%s]:'\n", 316 | "```" 317 | ] 318 | }, 319 | { 320 | "cell_type": "markdown", 321 | "metadata": {}, 322 | "source": [ 323 | "#### `nbsphinx_prolog`\n", 324 | "\n", 325 | "See [Prolog and Epilog](prolog-and-epilog.ipynb)." 326 | ] 327 | }, 328 | { 329 | "cell_type": "markdown", 330 | "metadata": {}, 331 | "source": [ 332 | "#### `nbsphinx_prompt_width`\n", 333 | "\n", 334 | "Width of input/output prompts (HTML only).\n", 335 | "\n", 336 | "If a prompt is wider than that, it protrudes into the left margin.\n", 337 | "\n", 338 | "Any CSS length can be specified." 339 | ] 340 | }, 341 | { 342 | "cell_type": "markdown", 343 | "metadata": {}, 344 | "source": [ 345 | "#### `nbsphinx_requirejs_options`\n", 346 | "\n", 347 | "Options for loading RequireJS.\n", 348 | "See [nbsphinx_requirejs_path](#nbsphinx_requirejs_path)." 349 | ] 350 | }, 351 | { 352 | "cell_type": "markdown", 353 | "metadata": {}, 354 | "source": [ 355 | "#### `nbsphinx_requirejs_path`\n", 356 | "\n", 357 | "URL or local path to override the default URL\n", 358 | "for [RequireJS](https://requirejs.org/).\n", 359 | "\n", 360 | "If you use a local file,\n", 361 | "it should be located in a directory listed in\n", 362 | "[html_static_path](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path).\n", 363 | "\n", 364 | "Set to empty string to disable loading RequireJS." 365 | ] 366 | }, 367 | { 368 | "cell_type": "markdown", 369 | "metadata": {}, 370 | "source": [ 371 | "#### `nbsphinx_responsive_width`\n", 372 | "\n", 373 | "If the browser window is narrower than this,\n", 374 | "input/output prompts are on separate lines\n", 375 | "(HTML only).\n", 376 | "\n", 377 | "Any CSS length can be specified." 378 | ] 379 | }, 380 | { 381 | "cell_type": "markdown", 382 | "metadata": {}, 383 | "source": [ 384 | "#### `nbsphinx_thumbnails`\n", 385 | "\n", 386 | "A dictionary mapping from a document name\n", 387 | "(i.e. source file without suffix but with subdirectories)\n", 388 | "-- optionally containing wildcards --\n", 389 | "to a thumbnail path to be used in a\n", 390 | "[thumbnail gallery](subdir/gallery.ipynb). Thumbnails specified\n", 391 | "in notebooks will override those provided in this dictionary.\n", 392 | "\n", 393 | "See [Specifying Thumbnails](gallery/thumbnail-from-conf-py.ipynb)." 394 | ] 395 | }, 396 | { 397 | "cell_type": "markdown", 398 | "metadata": {}, 399 | "source": [ 400 | "#### `nbsphinx_timeout`\n", 401 | "\n", 402 | "Controls when a cell will time out.\n", 403 | "The timeout is given in seconds.\n", 404 | "Given `-1`, cells will never time out,\n", 405 | "which is also the default.\n", 406 | "\n", 407 | "See [Cell Execution Timeout](timeout.ipynb)." 408 | ] 409 | }, 410 | { 411 | "cell_type": "markdown", 412 | "metadata": {}, 413 | "source": [ 414 | "#### `nbsphinx_widgets_options`\n", 415 | "\n", 416 | "Options for loading Jupyter widgets resources.\n", 417 | "See [nbsphinx_widgets_path](#nbsphinx_widgets_path)." 418 | ] 419 | }, 420 | { 421 | "cell_type": "markdown", 422 | "metadata": {}, 423 | "source": [ 424 | "#### `nbsphinx_widgets_path`\n", 425 | "\n", 426 | "URL or local path to override the default URL\n", 427 | "for Jupyter widgets resources.\n", 428 | "See [Interactive Widgets (HTML only)](code-cells.ipynb#Interactive-Widgets-(HTML-only)).\n", 429 | "\n", 430 | "If you use a local file,\n", 431 | "it should be located in a directory listed in\n", 432 | "[html_static_path](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path).\n", 433 | "\n", 434 | "For loading the widgets resources,\n", 435 | "RequireJS is needed,\n", 436 | "see [nbsphinx_requirejs_path](#nbsphinx_requirejs_path).\n", 437 | "\n", 438 | "If `nbsphinx_widgets_path` is not specified,\n", 439 | "widgets resources are only loaded if at least one notebook\n", 440 | "actually uses widgets.\n", 441 | "If you are loading the relevant JavaScript code by some other means already,\n", 442 | "you can set this option to the empty string to avoid loading it a second time." 443 | ] 444 | } 445 | ], 446 | "metadata": { 447 | "kernelspec": { 448 | "display_name": "Python 3 (ipykernel)", 449 | "language": "python", 450 | "name": "python3" 451 | }, 452 | "language_info": { 453 | "codemirror_mode": { 454 | "name": "ipython", 455 | "version": 3 456 | }, 457 | "file_extension": ".py", 458 | "mimetype": "text/x-python", 459 | "name": "python", 460 | "nbconvert_exporter": "python", 461 | "pygments_lexer": "ipython3", 462 | "version": "3.11.1" 463 | } 464 | }, 465 | "nbformat": 4, 466 | "nbformat_minor": 4 467 | } 468 | -------------------------------------------------------------------------------- /doc/configuring-kernels.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Configuring the Kernels" 17 | ] 18 | }, 19 | { 20 | "cell_type": "markdown", 21 | "metadata": {}, 22 | "source": [ 23 | "## Kernel Name\n", 24 | "\n", 25 | "If we have multiple kernels installed, we can choose to override the kernel saved in the notebook using [nbsphinx_kernel_name](configuration.ipynb#nbsphinx_kernel_name):\n", 26 | "```python\n", 27 | "nbsphinx_kernel_name = 'python-upstream-dev'\n", 28 | "```\n", 29 | "which uses the kernel named `python-upstream-dev` instead of the kernel name stored in the notebook." 30 | ] 31 | }, 32 | { 33 | "cell_type": "markdown", 34 | "metadata": {}, 35 | "source": [ 36 | "## Kernel Arguments\n", 37 | "\n", 38 | "We can pass arguments to the kernel by using\n", 39 | "[nbsphinx_execute_arguments](configuration.ipynb#nbsphinx_execute_arguments),\n", 40 | "for example to set [plot options](code-cells.ipynb#Plots):\n", 41 | "\n", 42 | "```python\n", 43 | "nbsphinx_execute_arguments = [\n", 44 | " \"--InlineBackend.figure_formats={'svg', 'pdf'}\",\n", 45 | "]\n", 46 | "```" 47 | ] 48 | }, 49 | { 50 | "cell_type": "markdown", 51 | "metadata": {}, 52 | "source": [ 53 | "## Environment Variables\n", 54 | "\n", 55 | "The contents of `os.environ` after the execution of `conf.py` will be passed as environment variables to the kernel. As an example, `MY_DUMMY_VARIABLE` has been set in [conf.py](conf.py) like this:\n", 56 | "\n", 57 | "```python\n", 58 | "import os\n", 59 | "os.environ['MY_DUMMY_VARIABLE'] = 'Hello from conf.py!'\n", 60 | "```\n", 61 | "\n", 62 | "... and it can be checked in the notebook like this:" 63 | ] 64 | }, 65 | { 66 | "cell_type": "code", 67 | "execution_count": null, 68 | "metadata": {}, 69 | "outputs": [], 70 | "source": [ 71 | "import os\n", 72 | "os.environ['MY_DUMMY_VARIABLE']" 73 | ] 74 | }, 75 | { 76 | "cell_type": "markdown", 77 | "metadata": {}, 78 | "source": [ 79 | "This is useful if we want to edit `PYTHONPATH` in order to compile the documentation without installing the project:\n", 80 | "```python\n", 81 | "import os\n", 82 | "\n", 83 | "src = os.path.abspath('../src')\n", 84 | "os.environ['PYTHONPATH'] = src\n", 85 | "```" 86 | ] 87 | }, 88 | { 89 | "cell_type": "markdown", 90 | "metadata": {}, 91 | "source": [ 92 | "If you are using https://mybinder.org/ and you want to define environment variables,\n", 93 | "you should create a file `.binder/start` in your repository\n", 94 | "(see [Binder docs](https://mybinder.readthedocs.io/en/latest/using/config_files.html#start-run-code-before-the-user-sessions-starts))\n", 95 | "containing definitions like this:\n", 96 | "\n", 97 | "```bash\n", 98 | "#!/bin/bash\n", 99 | "export MY_DUMMY_VARIABLE=\"Hello from .binder/start!\"\n", 100 | "exec \"$@\"\n", 101 | "```" 102 | ] 103 | } 104 | ], 105 | "metadata": { 106 | "kernelspec": { 107 | "display_name": "Python 3", 108 | "language": "python", 109 | "name": "python3" 110 | }, 111 | "language_info": { 112 | "codemirror_mode": { 113 | "name": "ipython", 114 | "version": 3 115 | }, 116 | "file_extension": ".py", 117 | "mimetype": "text/x-python", 118 | "name": "python", 119 | "nbconvert_exporter": "python", 120 | "pygments_lexer": "ipython3", 121 | "version": "3.7.6rc1" 122 | } 123 | }, 124 | "nbformat": 4, 125 | "nbformat_minor": 2 126 | } 127 | -------------------------------------------------------------------------------- /doc/contributing.rst: -------------------------------------------------------------------------------- 1 | .. include:: ../CONTRIBUTING.rst 2 | -------------------------------------------------------------------------------- /doc/custom-css.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": {}, 6 | "source": [ 7 | "# Custom CSS\n", 8 | "\n", 9 | "If you are not satisfied with the CSS styles\n", 10 | "provided by `nbsphinx`\n", 11 | "and by your Sphinx theme,\n", 12 | "don't worry,\n", 13 | "you can add your own styles easily." 14 | ] 15 | }, 16 | { 17 | "cell_type": "markdown", 18 | "metadata": {}, 19 | "source": [ 20 | "## For All Pages\n", 21 | "\n", 22 | "Just create your own CSS file, e.g. `my-own-style.css`,\n", 23 | "and put it into the `_static/` sub-directory\n", 24 | "of your source directory.\n", 25 | "\n", 26 | "You'll also have to set the config values\n", 27 | "[html_static_path](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path)\n", 28 | "and\n", 29 | "[html_css_files](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files)\n", 30 | "in your `conf.py`, e.g. like this:\n", 31 | "\n", 32 | "```python\n", 33 | "html_static_path = ['_static']\n", 34 | "html_css_files = ['my-own-style.css']\n", 35 | "```" 36 | ] 37 | }, 38 | { 39 | "cell_type": "markdown", 40 | "metadata": {}, 41 | "source": [ 42 | "## For All RST files\n", 43 | "\n", 44 | "If you want your style to only apply to `*.rst` files\n", 45 | "(and not Jupyter notebooks or other source files),\n", 46 | "you can use\n", 47 | "[rst_prolog](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_prolog)\n", 48 | "with the\n", 49 | "[raw](https://docutils.sourceforge.io/docs/ref/rst/directives.html#raw-data-pass-through)\n", 50 | "directive in your `conf.py` like this:\n", 51 | "\n", 52 | "```python\n", 53 | "rst_prolog = \"\"\"\n", 54 | ".. raw:: html\n", 55 | "\n", 56 | " \n", 61 | "\"\"\"\n", 62 | "```" 63 | ] 64 | }, 65 | { 66 | "cell_type": "markdown", 67 | "metadata": {}, 68 | "source": [ 69 | "## For All Notebooks\n", 70 | "\n", 71 | "Similarly,\n", 72 | "if you want your style to only apply to notebooks,\n", 73 | "you can use [nbsphinx_prolog](prolog-and-epilog.ipynb)\n", 74 | "like this:\n", 75 | "\n", 76 | "```python\n", 77 | "nbsphinx_prolog = \"\"\"\n", 78 | ".. raw:: html\n", 79 | "\n", 80 | " \n", 85 | "\"\"\"\n", 86 | "```" 87 | ] 88 | }, 89 | { 90 | "cell_type": "markdown", 91 | "metadata": {}, 92 | "source": [ 93 | "## For a Single Notebook\n", 94 | "\n", 95 | "For styles that should affect only the current notebook,\n", 96 | "you can simply insert ` \n", 106 | "```\n", 107 | "\n", 108 | "\n", 114 | "\n", 115 | "This CSS example removes the input and output prompts\n", 116 | "from code cells,\n", 117 | "see the following cell:" 118 | ] 119 | }, 120 | { 121 | "cell_type": "code", 122 | "execution_count": null, 123 | "metadata": {}, 124 | "outputs": [], 125 | "source": [ 126 | "6 * 7" 127 | ] 128 | } 129 | ], 130 | "metadata": { 131 | "kernelspec": { 132 | "display_name": "Python 3", 133 | "language": "python", 134 | "name": "python3" 135 | }, 136 | "language_info": { 137 | "codemirror_mode": { 138 | "name": "ipython", 139 | "version": 3 140 | }, 141 | "file_extension": ".py", 142 | "mimetype": "text/x-python", 143 | "name": "python", 144 | "nbconvert_exporter": "python", 145 | "pygments_lexer": "ipython3", 146 | "version": "3.8.2" 147 | } 148 | }, 149 | "nbformat": 4, 150 | "nbformat_minor": 4 151 | } 152 | -------------------------------------------------------------------------------- /doc/custom-formats.pct.py: -------------------------------------------------------------------------------- 1 | # %% [markdown] 2 | # # Custom Notebook Formats 3 | # 4 | # By default, Jupyter notebooks are stored in files with the suffix `.ipynb`, 5 | # which use the JSON format for storage. 6 | # 7 | # However, there are libraries available which allow storing notebooks 8 | # in different formats, using different file suffixes. 9 | # 10 | # To use a custom notebook format in `nbsphinx`, you can specify the 11 | # `nbsphinx_custom_formats` option in your `conf.py` file. 12 | # You have to provide the file extension 13 | # and a conversion function that takes the contents of a file (as a string) 14 | # and returns a Jupyter notebook object. 15 | # 16 | # ```python 17 | # nbsphinx_custom_formats = { 18 | # '.mysuffix': 'mylibrary.converter_function', 19 | # } 20 | # ``` 21 | # 22 | # The converter function can be given as a string (recommended) 23 | # or as a function object. 24 | # 25 | # If a conversion function takes more than a single string argument, 26 | # you can specify the function name plus a dictionary with keyword arguments 27 | # which will be passed to the conversion function in addition to the 28 | # file contents. 29 | # 30 | # ```python 31 | # nbsphinx_custom_formats = { 32 | # '.mysuffix': ['mylibrary.converter_function', {'some_arg': 42}], 33 | # } 34 | # ``` 35 | # 36 | # You can of course use multiple formats 37 | # by specifying multiple conversion functions. 38 | 39 | # %% [markdown] 40 | # ## Example: Jupytext 41 | # 42 | # One example for a library which provides a custom conversion function is 43 | # [jupytext](https://github.com/mwouts/jupytext), 44 | # which allows storing the contents of Jupyter notebooks in 45 | # Markdown and R-Markdown, as well as plain Julia, Python and R files. 46 | # 47 | # Since its conversion function takes more than a single string argument, 48 | # we have to pass a keyword argument, e.g.: 49 | # 50 | # ```python 51 | # nbsphinx_custom_formats = { 52 | # '.Rmd': ['jupytext.reads', {'fmt': 'Rmd'}], 53 | # } 54 | # ``` 55 | 56 | # %% [markdown] 57 | # This very page is an example of a notebook stored in the 58 | # `py:percent` format 59 | # (see [docs](https://jupytext.readthedocs.io/en/latest/formats-scripts.html#the-percent-format)): 60 | 61 | # %% 62 | # !head -20 custom-formats.pct.py 63 | 64 | # %% [raw] raw_mimetype="text/restructuredtext" 65 | # To select a suitable conversion function, 66 | # we use the following setting in :download:`conf.py`: 67 | # 68 | # .. literalinclude:: conf.py 69 | # :language: python 70 | # :start-at: nbsphinx_custom_formats 71 | # :lines: -4 72 | # :emphasize-lines: 2 73 | 74 | # %% [markdown] 75 | # Another example is [this gallery example page](gallery/due-rst.pct.py). 76 | -------------------------------------------------------------------------------- /doc/executing-notebooks.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Controlling Notebook Execution\n", 17 | "\n", 18 | "Notebooks with no outputs are automatically executed during the Sphinx build process.\n", 19 | "If, however, there is at least one output cell present, the notebook is not evaluated and included as is.\n", 20 | "\n", 21 | "The following notebooks show how this default behavior can be used and customized." 22 | ] 23 | }, 24 | { 25 | "cell_type": "markdown", 26 | "metadata": { 27 | "nbsphinx-toctree": {} 28 | }, 29 | "source": [ 30 | "* [Pre-Executing Notebooks](pre-executed.ipynb)\n", 31 | "* [Explicitly Dis-/Enabling Notebook Execution](never-execute.ipynb)\n", 32 | "* [Ignoring Errors](allow-errors.ipynb)\n", 33 | "* [Ignoring Errors on a Per-Cell Basis](allow-errors-per-cell.ipynb)\n", 34 | "* [Configuring Kernels](configuring-kernels.ipynb)\n", 35 | "* [Cell Execution Timeout](timeout.ipynb)" 36 | ] 37 | } 38 | ], 39 | "metadata": { 40 | "kernelspec": { 41 | "display_name": "Python 3", 42 | "language": "python", 43 | "name": "python3" 44 | }, 45 | "language_info": { 46 | "codemirror_mode": { 47 | "name": "ipython", 48 | "version": 3 49 | }, 50 | "file_extension": ".py", 51 | "mimetype": "text/x-python", 52 | "name": "python", 53 | "nbconvert_exporter": "python", 54 | "pygments_lexer": "ipython3", 55 | "version": "3.7.4+" 56 | } 57 | }, 58 | "nbformat": 4, 59 | "nbformat_minor": 4 60 | } 61 | -------------------------------------------------------------------------------- /doc/fallback_theme.txt: -------------------------------------------------------------------------------- 1 | insipid-sphinx-theme 2 | -------------------------------------------------------------------------------- /doc/favicon.svg: -------------------------------------------------------------------------------- 1 | 2 | 7 | 8 | 9 | -------------------------------------------------------------------------------- /doc/gallery/cell-metadata.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Using Cell Metadata to Select a Thumbnail\n", 17 | "\n", 18 | "If the [nbsphinx-thumbnail](cell-tag.ipynb) cell tag is not enough,\n", 19 | "you can use cell metadata to specify more options.\n", 20 | "\n", 21 | "The last cell in this notebook has this metadata:\n", 22 | "\n", 23 | "```json\n", 24 | "{\n", 25 | " \"nbsphinx-thumbnail\": {\n", 26 | " \"tooltip\": \"This tooltip message was defined in cell metadata\"\n", 27 | " }\n", 28 | "}\n", 29 | "```\n", 30 | "\n", 31 | "If there are multiple outputs in the selected cell,\n", 32 | "the last one is used.\n", 33 | "See [Choosing from Multiple Outputs](multiple-outputs.ipynb)\n", 34 | "for how to select a specific output." 35 | ] 36 | }, 37 | { 38 | "cell_type": "code", 39 | "execution_count": null, 40 | "metadata": {}, 41 | "outputs": [], 42 | "source": [ 43 | "import matplotlib.pyplot as plt\n", 44 | "import numpy as np" 45 | ] 46 | }, 47 | { 48 | "cell_type": "code", 49 | "execution_count": null, 50 | "metadata": {}, 51 | "outputs": [], 52 | "source": [ 53 | "plt.rcParams['image.cmap'] = 'coolwarm'\n", 54 | "plt.rcParams['image.origin'] = 'lower'" 55 | ] 56 | }, 57 | { 58 | "cell_type": "markdown", 59 | "metadata": {}, 60 | "source": [ 61 | "Some example data stolen from\n", 62 | "https://matplotlib.org/examples/pylab_examples/pcolor_demo.html:" 63 | ] 64 | }, 65 | { 66 | "cell_type": "code", 67 | "execution_count": null, 68 | "metadata": {}, 69 | "outputs": [], 70 | "source": [ 71 | "x, y = np.meshgrid(np.arange(-3, 3, 0.1), np.arange(-2, 2, 0.1))\n", 72 | "z = (1 - x / 2 + x ** 5 + y ** 3) * np.exp(-x ** 2 - y ** 2)" 73 | ] 74 | }, 75 | { 76 | "cell_type": "code", 77 | "execution_count": null, 78 | "metadata": {}, 79 | "outputs": [], 80 | "source": [ 81 | "zmax = np.max(np.abs(z))" 82 | ] 83 | }, 84 | { 85 | "cell_type": "code", 86 | "execution_count": null, 87 | "metadata": { 88 | "nbsphinx-thumbnail": { 89 | "tooltip": "This tooltip message was defined in cell metadata" 90 | } 91 | }, 92 | "outputs": [], 93 | "source": [ 94 | "fig, ax = plt.subplots(figsize=[5, 3.5])\n", 95 | "ax.imshow(z, vmin=-zmax, vmax=zmax)" 96 | ] 97 | } 98 | ], 99 | "metadata": { 100 | "kernelspec": { 101 | "display_name": "Python 3", 102 | "language": "python", 103 | "name": "python3" 104 | }, 105 | "language_info": { 106 | "codemirror_mode": { 107 | "name": "ipython", 108 | "version": 3 109 | }, 110 | "file_extension": ".py", 111 | "mimetype": "text/x-python", 112 | "name": "python", 113 | "nbconvert_exporter": "python", 114 | "pygments_lexer": "ipython3", 115 | "version": "3.7.6" 116 | } 117 | }, 118 | "nbformat": 4, 119 | "nbformat_minor": 4 120 | } 121 | -------------------------------------------------------------------------------- /doc/gallery/cell-tag.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Using a Cell Tag to Select a Thumbnail\n", 17 | "\n", 18 | "You can select any code cell (with appropriate output)\n", 19 | "by tagging it with the `nbsphinx-thumbnail` tag.\n", 20 | "\n", 21 | "If there are multiple outputs in the selected cell,\n", 22 | "the last one is used.\n", 23 | "See [Choosing from Multiple Outputs](multiple-outputs.ipynb)\n", 24 | "for how to select a specific output.\n", 25 | "If you want to show a tooltip, have a look at\n", 26 | "[Using Cell Metadata to Select a Thumbnail](cell-metadata.ipynb)." 27 | ] 28 | }, 29 | { 30 | "cell_type": "code", 31 | "execution_count": null, 32 | "metadata": {}, 33 | "outputs": [], 34 | "source": [ 35 | "import matplotlib.pyplot as plt" 36 | ] 37 | }, 38 | { 39 | "cell_type": "markdown", 40 | "metadata": {}, 41 | "source": [ 42 | "The following cell has the `nbsphinx-thumbnail` tag, which will take precedence over the default of the last image in the notebook:" 43 | ] 44 | }, 45 | { 46 | "cell_type": "code", 47 | "execution_count": null, 48 | "metadata": { 49 | "tags": [ 50 | "nbsphinx-thumbnail" 51 | ] 52 | }, 53 | "outputs": [], 54 | "source": [ 55 | "fig, ax = plt.subplots(figsize=[6, 3])\n", 56 | "ax.plot([4, 9, 7, 20, 6, 33, 13, 23, 16, 62, 8])" 57 | ] 58 | }, 59 | { 60 | "cell_type": "markdown", 61 | "metadata": {}, 62 | "source": [ 63 | "Although the next cell has an image, it won't be used as the thumbnail, due to the tag on the one above." 64 | ] 65 | }, 66 | { 67 | "cell_type": "code", 68 | "execution_count": null, 69 | "metadata": {}, 70 | "outputs": [], 71 | "source": [ 72 | "fig, ax = plt.subplots(figsize=[6, 3])\n", 73 | "ax.scatter(range(10), [0, 8, 9, 1, -8, -10, -3, 7, 10, 4])" 74 | ] 75 | } 76 | ], 77 | "metadata": { 78 | "kernelspec": { 79 | "display_name": "Python 3", 80 | "language": "python", 81 | "name": "python3" 82 | }, 83 | "language_info": { 84 | "codemirror_mode": { 85 | "name": "ipython", 86 | "version": 3 87 | }, 88 | "file_extension": ".py", 89 | "mimetype": "text/x-python", 90 | "name": "python", 91 | "nbconvert_exporter": "python", 92 | "pygments_lexer": "ipython3", 93 | "version": "3.7.6" 94 | } 95 | }, 96 | "nbformat": 4, 97 | "nbformat_minor": 4 98 | } 99 | -------------------------------------------------------------------------------- /doc/gallery/cinque-rst.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Dummy Notebook 5 for Gallery\n", 17 | "\n", 18 | "This is another dummy file to fill\n", 19 | "[the gallery in the reST file](../a-normal-rst-file.rst#thumbnail-galleries).\n", 20 | "\n", 21 | "The thumbnail image is assigned in [conf.py](../conf.py)." 22 | ] 23 | }, 24 | { 25 | "cell_type": "markdown", 26 | "metadata": {}, 27 | "source": [ 28 | "This page has a secondary use, though,\n", 29 | "which is testing whether a single inline math equation works\n", 30 | "(if there is no other math on the same page): $\\text{e}^{i\\pi} = -1$." 31 | ] 32 | } 33 | ], 34 | "metadata": { 35 | "kernelspec": { 36 | "display_name": "Python 3", 37 | "language": "python", 38 | "name": "python3" 39 | }, 40 | "language_info": { 41 | "codemirror_mode": { 42 | "name": "ipython", 43 | "version": 3 44 | }, 45 | "file_extension": ".py", 46 | "mimetype": "text/x-python", 47 | "name": "python", 48 | "nbconvert_exporter": "python", 49 | "pygments_lexer": "ipython3", 50 | "version": "3.7.6" 51 | } 52 | }, 53 | "nbformat": 4, 54 | "nbformat_minor": 4 55 | } 56 | -------------------------------------------------------------------------------- /doc/gallery/default-thumbnail.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Default Thumbnail\n", 17 | "\n", 18 | "By default,\n", 19 | "the last image output of a notebook will be used as its thumbnail.\n", 20 | "Without an image output, a placeholder will be used.\n", 21 | "See [a notebook with no thumbnail](no-thumbnail.ipynb) for an example.\n", 22 | "\n", 23 | "However, if a thumbnail is explicitly assigned by\n", 24 | "[Using Cell Metadata to Select a Thumbnail](cell-metadata.ipynb),\n", 25 | "[Using a Cell Tag to Select a Thumbnail](cell-tag.ipynb) or\n", 26 | "[Specifying a Thumbnail File](thumbnail-from-conf-py.ipynb),\n", 27 | "these methods will take precedence." 28 | ] 29 | }, 30 | { 31 | "cell_type": "code", 32 | "execution_count": null, 33 | "metadata": {}, 34 | "outputs": [], 35 | "source": [ 36 | "import matplotlib.pyplot as plt\n", 37 | "import numpy as np" 38 | ] 39 | }, 40 | { 41 | "cell_type": "markdown", 42 | "metadata": {}, 43 | "source": [ 44 | "Although the next cell contains an image (a plot), it won't be used as the thumbnail because it's not the last in the notebook, and we haven't explicitly tagged it." 45 | ] 46 | }, 47 | { 48 | "cell_type": "code", 49 | "execution_count": null, 50 | "metadata": {}, 51 | "outputs": [], 52 | "source": [ 53 | "fig, ax = plt.subplots(figsize=[6, 3])\n", 54 | "x = np.linspace(-5, 5, 50)\n", 55 | "ax.plot(x, np.sinc(x));" 56 | ] 57 | }, 58 | { 59 | "cell_type": "markdown", 60 | "metadata": {}, 61 | "source": [ 62 | "But the next cell is the last containing an image in the notebook,\n", 63 | "so its last image output will be used as the thumbnail." 64 | ] 65 | }, 66 | { 67 | "cell_type": "code", 68 | "execution_count": null, 69 | "metadata": {}, 70 | "outputs": [], 71 | "source": [ 72 | "display(fig)\n", 73 | "fig, ax = plt.subplots(figsize=[6, 3])\n", 74 | "x = np.linspace(-5, 5, 50)\n", 75 | "ax.plot(x, -np.sinc(x), color='red');" 76 | ] 77 | } 78 | ], 79 | "metadata": { 80 | "kernelspec": { 81 | "display_name": "Python 3 (ipykernel)", 82 | "language": "python", 83 | "name": "python3" 84 | }, 85 | "language_info": { 86 | "codemirror_mode": { 87 | "name": "ipython", 88 | "version": 3 89 | }, 90 | "file_extension": ".py", 91 | "mimetype": "text/x-python", 92 | "name": "python", 93 | "nbconvert_exporter": "python", 94 | "pygments_lexer": "ipython3", 95 | "version": "3.11.2" 96 | } 97 | }, 98 | "nbformat": 4, 99 | "nbformat_minor": 4 100 | } 101 | -------------------------------------------------------------------------------- /doc/gallery/due-rst.pct.py: -------------------------------------------------------------------------------- 1 | # %% [markdown] 2 | # # Dummy Notebook 2 for Gallery 3 | # 4 | # This is a dummy file just to fill 5 | # [the gallery in the reST file](../a-normal-rst-file.rst#thumbnail-galleries). 6 | # 7 | # The thumbnail image is assigned in [conf.py](../conf.py). 8 | 9 | # %% [markdown] 10 | # The source file is, for no particular reason, 11 | # a Python script adhering to the `py:percent` format. 12 | # It is parsed with the help of [Jupytext](https://jupytext.readthedocs.io/), 13 | # see [Custom Notebook Formats](../custom-formats.ipynb). 14 | 15 | # %% 16 | from pathlib import Path 17 | 18 | # %% 19 | filename = 'due-rst.pct.py' 20 | 21 | print(Path(filename).read_text()) 22 | 23 | # %% [markdown] 24 | # This page has a secondary use, 25 | # which is testing whether a single math output cell works 26 | # (if there is no other math on the same page): 27 | 28 | # %% 29 | from IPython.display import Math 30 | eq = Math(r'\int\limits_{-\infty}^\infty f(x) \delta(x - x_0) dx = f(x_0)') 31 | eq 32 | -------------------------------------------------------------------------------- /doc/gallery/gallery-with-links.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Gallery With Links (HTML only)\n", 17 | "\n", 18 | "Contrary to\n", 19 | "[nbsphinx-gallery](gallery-with-nested-documents.ipynb),\n", 20 | "the cell tag/metadata `nbsphinx-link-gallery`\n", 21 | "creates a gallery from notebooks (and other source) files\n", 22 | "without including them as sub-sections.\n", 23 | "Other than that, it works in a similar way,\n", 24 | "but only the options\n", 25 | "`\"name\"`,\n", 26 | "`\"caption\"` and\n", 27 | "`\"reversed\"` are supported.\n", 28 | "In LaTeX output, this has no effect.\n", 29 | "The cell is ignored and nothing is added to the LaTeX document.\n", 30 | "\n", 31 | "In reST files\n", 32 | "(and [raw reST cells](../raw-cells.ipynb#reST)),\n", 33 | "the\n", 34 | "[nblinkgallery](../a-normal-rst-file.rst#thumbnail-link-galleries-html-only)\n", 35 | "directive can be used.\n", 36 | "\n", 37 | "The following Markdown cell\n", 38 | "has the `nbsphinx-link-gallery` tag,\n", 39 | "which turns the contained links into a gallery\n", 40 | "and uses the first section title as `caption`:" 41 | ] 42 | }, 43 | { 44 | "cell_type": "markdown", 45 | "metadata": { 46 | "tags": [ 47 | "nbsphinx-link-gallery" 48 | ] 49 | }, 50 | "source": [ 51 | "## This is a thumbnail gallery with links to existing documents:\n", 52 | "\n", 53 | "This paragraph will be ignored.\n", 54 | "Only links are taken into account.\n", 55 | "\n", 56 | "## This section title will be ignored\n", 57 | "\n", 58 | "... because only the first title in this cell is used.\n", 59 | "\n", 60 | "* [Dummy Notebook 2](due-rst.pct.py)\n", 61 | "* [An Orphan Notebook](../orphan.ipynb)\n", 62 | "* [Notebook About Code Cells](../code-cells.ipynb)\n", 63 | "* [Thumbnail With a Tooltip](cell-metadata.ipynb)\n", 64 | "* [A Page About Contributing (Not a Notebook)](../contributing.rst)\n", 65 | "* [A Page Using reStructuredText (Not a Notebook)](../a-normal-rst-file.rst)" 66 | ] 67 | } 68 | ], 69 | "metadata": { 70 | "kernelspec": { 71 | "display_name": "Python 3 (ipykernel)", 72 | "language": "python", 73 | "name": "python3" 74 | }, 75 | "language_info": { 76 | "codemirror_mode": { 77 | "name": "ipython", 78 | "version": 3 79 | }, 80 | "file_extension": ".py", 81 | "mimetype": "text/x-python", 82 | "name": "python", 83 | "nbconvert_exporter": "python", 84 | "pygments_lexer": "ipython3", 85 | "version": "3.11.1" 86 | } 87 | }, 88 | "nbformat": 4, 89 | "nbformat_minor": 4 90 | } 91 | -------------------------------------------------------------------------------- /doc/gallery/gallery-with-nested-documents.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Gallery With Nested Documents\n", 17 | "\n", 18 | "You can create\n", 19 | "[thumbnail galleries in reST files](../a-normal-rst-file.rst#thumbnail-galleries),\n", 20 | "but you can also create such galleries in Jupyter notebooks\n", 21 | "by adding the `nbsphinx-gallery`\n", 22 | "cell tag or metadata,\n", 23 | "which is used just like the\n", 24 | "[nbsphinx-toctree](../subdir/toctree.ipynb) cell tag/metadata.\n", 25 | "For possible options, see the [toctree](../subdir/toctree.ipynb) notebook.\n", 26 | "\n", 27 | "
\n", 28 | "\n", 29 | "Note\n", 30 | "\n", 31 | "In LaTeX output this behaves just like ``toctree``,\n", 32 | "i.e. no thumbnail gallery is shown,\n", 33 | "but the linked files are included in the document.\n", 34 | "\n", 35 | "Like with ``toctree`` you should avoid adding content\n", 36 | "after a gallery (except other toctrees and galleries)\n", 37 | "because this content would appear in the LaTeX output\n", 38 | "*after* the content of all included source files,\n", 39 | "which is probably not what you want.\n", 40 | "\n", 41 | "
\n", 42 | "\n", 43 | "The following cell has the `nbsphinx-gallery` tag,\n", 44 | "which creates a thumbnail gallery.\n", 45 | "The *first* section title in that cell (if available)\n", 46 | "is used as `caption` (unless it is already given in the metadata).\n", 47 | "\n", 48 | "The notebooks in the following gallery describe different ways\n", 49 | "how to select which images are used as thumbnails.\n", 50 | "The notebooks are added as sub-sections under the current section,\n", 51 | "just like when using ``toctree``.\n", 52 | "If you want to create a gallery from links to notebooks\n", 53 | "that are already included somewhere else,\n", 54 | "you can use [nbsphinx-link-gallery](gallery-with-links.ipynb)." 55 | ] 56 | }, 57 | { 58 | "cell_type": "markdown", 59 | "metadata": { 60 | "tags": [ 61 | "nbsphinx-gallery" 62 | ] 63 | }, 64 | "source": [ 65 | "This section title will be used as ``caption``:\n", 66 | "\n", 67 | "## This is a thumbnail gallery with sub-documents:\n", 68 | "\n", 69 | "This paragraph will be ignored.\n", 70 | "Only links and the first section title are scanned,\n", 71 | "everything else is ignored.\n", 72 | "\n", 73 | "* [Last Image Is Used by Default](default-thumbnail.ipynb)\n", 74 | "* [Using a Cell Tag to Select a Thumbnail](cell-tag.ipynb)\n", 75 | "* [Using Cell Metadata to Select a Thumbnail and Provide a Tooltip](cell-metadata.ipynb)\n", 76 | "* [Choosing from Multiple Outputs](multiple-outputs.ipynb)\n", 77 | "* [No Thumbnail Available](no-thumbnail.ipynb)\n", 78 | "* [Specifying a Thumbnail File](thumbnail-from-conf-py.ipynb)\n", 79 | "\n", 80 | "## This section title will be ignored\n", 81 | "\n", 82 | "... because only the first title in this cell is used." 83 | ] 84 | } 85 | ], 86 | "metadata": { 87 | "kernelspec": { 88 | "display_name": "Python 3 (ipykernel)", 89 | "language": "python", 90 | "name": "python3" 91 | }, 92 | "language_info": { 93 | "codemirror_mode": { 94 | "name": "ipython", 95 | "version": 3 96 | }, 97 | "file_extension": ".py", 98 | "mimetype": "text/x-python", 99 | "name": "python", 100 | "nbconvert_exporter": "python", 101 | "pygments_lexer": "ipython3", 102 | "version": "3.11.2" 103 | } 104 | }, 105 | "nbformat": 4, 106 | "nbformat_minor": 4 107 | } 108 | -------------------------------------------------------------------------------- /doc/gallery/matplotlibrc: -------------------------------------------------------------------------------- 1 | ../matplotlibrc -------------------------------------------------------------------------------- /doc/gallery/multiple-outputs.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Choosing from Multiple Outputs\n", 17 | "\n", 18 | "By default, the last output of the selected cell is used as a thumbnail.\n", 19 | "If that's what you want, you can simply use the\n", 20 | "[nbsphinx-thumbnail](cell-tag.ipynb) cell tag.\n", 21 | "\n", 22 | "If you want to specify one of multiple outputs,\n", 23 | "you can add a (zero-based) `\"output-index\"`\n", 24 | "to your `\"nbsphinx-thumbnail\"` cell metadata.\n", 25 | "\n", 26 | "The following cell has this metadata,\n", 27 | "selecting the third output to be used as thumbnail in\n", 28 | "[the gallery](gallery-with-nested-documents.ipynb).\n", 29 | "\n", 30 | "```json\n", 31 | "{\n", 32 | " \"nbsphinx-thumbnail\": {\n", 33 | " \"output-index\": 2\n", 34 | " }\n", 35 | "}\n", 36 | "```" 37 | ] 38 | }, 39 | { 40 | "cell_type": "code", 41 | "execution_count": null, 42 | "metadata": { 43 | "nbsphinx-thumbnail": { 44 | "output-index": 2 45 | } 46 | }, 47 | "outputs": [], 48 | "source": [ 49 | "from IPython.display import Image\n", 50 | "\n", 51 | "display(Image(url='https://jupyter.org/assets/homepage/main-logo.svg'))\n", 52 | "print('Hello!')\n", 53 | "display(Image(filename='../images/notebook_icon.png'))\n", 54 | "display(Image(url='https://www.python.org/static/img/python-logo-large.png', embed=True))" 55 | ] 56 | } 57 | ], 58 | "metadata": { 59 | "kernelspec": { 60 | "display_name": "Python 3 (ipykernel)", 61 | "language": "python", 62 | "name": "python3" 63 | }, 64 | "language_info": { 65 | "codemirror_mode": { 66 | "name": "ipython", 67 | "version": 3 68 | }, 69 | "file_extension": ".py", 70 | "mimetype": "text/x-python", 71 | "name": "python", 72 | "nbconvert_exporter": "python", 73 | "pygments_lexer": "ipython3", 74 | "version": "3.11.1" 75 | } 76 | }, 77 | "nbformat": 4, 78 | "nbformat_minor": 4 79 | } 80 | -------------------------------------------------------------------------------- /doc/gallery/no-thumbnail.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# A Notebook without Thumbnail\n", 17 | "\n", 18 | "This notebook doesn't contain any thumbnail metadata.\n", 19 | "\n", 20 | "It should be displayed with the default thumbnail image in the\n", 21 | "[gallery](gallery-with-nested-documents.ipynb)." 22 | ] 23 | } 24 | ], 25 | "metadata": { 26 | "kernelspec": { 27 | "display_name": "Python 3 (ipykernel)", 28 | "language": "python", 29 | "name": "python3" 30 | }, 31 | "language_info": { 32 | "codemirror_mode": { 33 | "name": "ipython", 34 | "version": 3 35 | }, 36 | "file_extension": ".py", 37 | "mimetype": "text/x-python", 38 | "name": "python", 39 | "nbconvert_exporter": "python", 40 | "pygments_lexer": "ipython3", 41 | "version": "3.11.1" 42 | } 43 | }, 44 | "nbformat": 4, 45 | "nbformat_minor": 4 46 | } 47 | -------------------------------------------------------------------------------- /doc/gallery/thumbnail-from-conf-py.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Specifying Thumbnails in `conf.py`\n", 17 | "\n", 18 | "This notebook doesn't contain a `nbsphinx-thumbnail`\n", 19 | "[cell tag](cell-tag.ipynb) nor\n", 20 | "[cell metadata](cell-metadata.ipynb).\n", 21 | "Instead, in the file [conf.py](../conf.py),\n", 22 | "a thumbnail is specified (via the\n", 23 | "[nbsphinx_thumbnails](../configuration.ipynb#nbsphinx_thumbnails)\n", 24 | "option),\n", 25 | "which will be used in the [gallery](gallery-with-nested-documents.ipynb).\n", 26 | "\n", 27 | "The keys in the `nbsphinx_thumbnails` dictionary can contain wildcards,\n", 28 | "which behave very similarly to the\n", 29 | "[html_sidebars](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars)\n", 30 | "option.\n", 31 | "\n", 32 | "The thumbnail files can be local image files somewhere in the source directory,\n", 33 | "but you'll need to create at least one\n", 34 | "[link](../markdown-cells.ipynb#Links-to-Local-Files)\n", 35 | "to them in order to copy them to the HTML output directory.\n", 36 | "\n", 37 | "You can also use files from the `_static` directory\n", 38 | "(which contains all files in your [html_static_path](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path)).\n", 39 | "\n", 40 | "If you want, you can also use files from the `_images` directory,\n", 41 | "which contains all notebook outputs." 42 | ] 43 | }, 44 | { 45 | "cell_type": "markdown", 46 | "metadata": {}, 47 | "source": [ 48 | "To demonstrate this feature,\n", 49 | "we are creating an image file here:" 50 | ] 51 | }, 52 | { 53 | "cell_type": "code", 54 | "execution_count": null, 55 | "metadata": {}, 56 | "outputs": [], 57 | "source": [ 58 | "import matplotlib.pyplot as plt" 59 | ] 60 | }, 61 | { 62 | "cell_type": "code", 63 | "execution_count": null, 64 | "metadata": {}, 65 | "outputs": [], 66 | "source": [ 67 | "fig, ax = plt.subplots()\n", 68 | "ax.plot([4, 8, 15, 16, 23, 42])\n", 69 | "fig.savefig('a-local-file.png')\n", 70 | "plt.close() # avoid plotting the figure" 71 | ] 72 | }, 73 | { 74 | "cell_type": "markdown", 75 | "metadata": {}, 76 | "source": [ 77 | "Please note that the previous cell doesn't have any outputs,\n", 78 | "but it has generated a file named `a-local-file.png` in the notebook's directory.\n", 79 | "\n", 80 | "We have to create a link to this file (which is a good idea anyway):\n", 81 | "[a-local-file.png](a-local-file.png).\n", 82 | "\n", 83 | "Now we can use this file in our [conf.py](../conf.py) like this:\n", 84 | "\n", 85 | "```python\n", 86 | "nbsphinx_thumbnails = {\n", 87 | " 'gallery/thumbnail-from-conf-py': 'gallery/a-local-file.png',\n", 88 | "}\n", 89 | "```\n", 90 | "\n", 91 | "Please note that the notebook name does *not* contain the `.ipynb` suffix." 92 | ] 93 | }, 94 | { 95 | "cell_type": "markdown", 96 | "metadata": {}, 97 | "source": [ 98 | "Note that the following plot is *not* used as a thumbnail\n", 99 | "because the `nbsphinx_thumbnails` setting overrides\n", 100 | "[the default behavior](default-thumbnail.ipynb)." 101 | ] 102 | }, 103 | { 104 | "cell_type": "code", 105 | "execution_count": null, 106 | "metadata": {}, 107 | "outputs": [], 108 | "source": [ 109 | "fig, ax = plt.subplots(figsize=[6, 3])\n", 110 | "ax.plot([4, 9, 7, 20, 6, 33, 13, 23, 16, 62, 8], 'r:');" 111 | ] 112 | } 113 | ], 114 | "metadata": { 115 | "kernelspec": { 116 | "display_name": "Python 3 (ipykernel)", 117 | "language": "python", 118 | "name": "python3" 119 | }, 120 | "language_info": { 121 | "codemirror_mode": { 122 | "name": "ipython", 123 | "version": 3 124 | }, 125 | "file_extension": ".py", 126 | "mimetype": "text/x-python", 127 | "name": "python", 128 | "nbconvert_exporter": "python", 129 | "pygments_lexer": "ipython3", 130 | "version": "3.11.2" 131 | } 132 | }, 133 | "nbformat": 4, 134 | "nbformat_minor": 4 135 | } 136 | -------------------------------------------------------------------------------- /doc/gallery/uno-rst.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Dummy Notebook 1 for Gallery\n", 17 | "\n", 18 | "This is a dummy file just to fill\n", 19 | "[the gallery in the reST file](../a-normal-rst-file.rst#thumbnail-galleries).\n", 20 | "\n", 21 | "The thumbnail image is assigned in [conf.py](../conf.py)." 22 | ] 23 | }, 24 | { 25 | "cell_type": "markdown", 26 | "metadata": {}, 27 | "source": [ 28 | "This page has a secondary use, though,\n", 29 | "which is testing whether a single block math equation works\n", 30 | "(if there is no other math on the same page):\n", 31 | "\n", 32 | "\\begin{equation}\n", 33 | "\\int\\limits_{-\\infty}^\\infty f(x) \\delta(x - x_0) dx = f(x_0).\n", 34 | "\\end{equation}" 35 | ] 36 | } 37 | ], 38 | "metadata": { 39 | "kernelspec": { 40 | "display_name": "Python 3", 41 | "language": "python", 42 | "name": "python3" 43 | }, 44 | "language_info": { 45 | "codemirror_mode": { 46 | "name": "ipython", 47 | "version": 3 48 | }, 49 | "file_extension": ".py", 50 | "mimetype": "text/x-python", 51 | "name": "python", 52 | "nbconvert_exporter": "python", 53 | "pygments_lexer": "ipython3", 54 | "version": "3.7.6" 55 | } 56 | }, 57 | "nbformat": 4, 58 | "nbformat_minor": 4 59 | } 60 | -------------------------------------------------------------------------------- /doc/hidden-cells.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Hidden Cells\n", 17 | "\n", 18 | "You can remove cells from the HTML/LaTeX output by adding this to the cell metadata:\n", 19 | "\n", 20 | "```\n", 21 | "\"nbsphinx\": \"hidden\"\n", 22 | "```\n", 23 | "\n", 24 | "Hidden cells are still executed but removed afterwards.\n", 25 | "\n", 26 | "For example, the following hidden cell defines the variable `answer`." 27 | ] 28 | }, 29 | { 30 | "cell_type": "code", 31 | "execution_count": null, 32 | "metadata": { 33 | "nbsphinx": "hidden" 34 | }, 35 | "outputs": [], 36 | "source": [ 37 | "answer = 6 * 7" 38 | ] 39 | }, 40 | { 41 | "cell_type": "markdown", 42 | "metadata": {}, 43 | "source": [ 44 | "This is the cell after the hidden cell.\n", 45 | "Although the previous cell is not visible, its result is still available:" 46 | ] 47 | }, 48 | { 49 | "cell_type": "code", 50 | "execution_count": null, 51 | "metadata": {}, 52 | "outputs": [], 53 | "source": [ 54 | "answer" 55 | ] 56 | }, 57 | { 58 | "cell_type": "markdown", 59 | "metadata": {}, 60 | "source": [ 61 | "Don't overuse this, because it may make it harder to follow what's going on in your notebook.\n", 62 | "\n", 63 | "Also Markdown cells can be hidden.\n", 64 | "The following cell is hidden." 65 | ] 66 | }, 67 | { 68 | "cell_type": "markdown", 69 | "metadata": { 70 | "nbsphinx": "hidden" 71 | }, 72 | "source": [ 73 | "I am a *hidden* Markdown cell!" 74 | ] 75 | }, 76 | { 77 | "cell_type": "markdown", 78 | "metadata": {}, 79 | "source": [ 80 | "This is the cell after the hidden cell." 81 | ] 82 | } 83 | ], 84 | "metadata": { 85 | "kernelspec": { 86 | "display_name": "Python 3", 87 | "language": "python", 88 | "name": "python3" 89 | }, 90 | "language_info": { 91 | "codemirror_mode": { 92 | "name": "ipython", 93 | "version": 3 94 | }, 95 | "file_extension": ".py", 96 | "mimetype": "text/x-python", 97 | "name": "python", 98 | "nbconvert_exporter": "python", 99 | "pygments_lexer": "ipython3", 100 | "version": "3.6.7" 101 | } 102 | }, 103 | "nbformat": 4, 104 | "nbformat_minor": 2 105 | } 106 | -------------------------------------------------------------------------------- /doc/images/notebook_icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/spatialaudio/nbsphinx/b7430090715c68eb1846d677b997c74892d51af1/doc/images/notebook_icon.png -------------------------------------------------------------------------------- /doc/images/raw_cells_jupyter_notebook.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/spatialaudio/nbsphinx/b7430090715c68eb1846d677b997c74892d51af1/doc/images/raw_cells_jupyter_notebook.png -------------------------------------------------------------------------------- /doc/images/raw_cells_jupyterlab.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/spatialaudio/nbsphinx/b7430090715c68eb1846d677b997c74892d51af1/doc/images/raw_cells_jupyterlab.png -------------------------------------------------------------------------------- /doc/index.rst: -------------------------------------------------------------------------------- 1 | .. include:: ../README.rst 2 | 3 | All of the following content 4 | was generated from Jupyter notebooks, 5 | except for the sections :doc:`a-normal-rst-file`, 6 | :doc:`contributing`, :doc:`references` and :doc:`version-history`, 7 | which were generated from Sphinx's built-in `reStructuredText`__ format. 8 | The sections 9 | :doc:`custom-formats`, 10 | :doc:`gallery/due-rst` and 11 | :doc:`a-markdown-file` 12 | are using alternative storage formats for Jupyter notebooks, 13 | see :doc:`custom-formats` for details. 14 | 15 | __ https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html 16 | 17 | .. raw:: html 18 | 19 |
20 | click here to see full table of contents 21 | 22 | .. toctree:: 23 | :maxdepth: 4 24 | :glob: 25 | 26 | installation 27 | usage 28 | configuration 29 | markdown-cells 30 | code-cells 31 | raw-cells 32 | hidden-cells 33 | executing-notebooks 34 | prolog-and-epilog 35 | custom-formats 36 | subdir/* 37 | custom-css 38 | a-normal-rst-file 39 | a-markdown-file 40 | links 41 | contributing 42 | references 43 | version-history 44 | 45 | .. only:: html 46 | 47 | There is also :ref:`/orphan.ipynb`, just for the sake of it. 48 | 49 | .. raw:: html 50 | 51 |
52 | 53 | .. only:: html and insipid 54 | 55 | .. admonition:: How To Navigate This Site 56 | 57 | Use the *next* and *previous* links at the top and the bottom of each page 58 | to flip through the pages. 59 | Alternatively, you can use the right and left arrow keys 60 | on your keyboard. 61 | Some additional keyboard shortcuts 62 | are provided via the `accesskey feature`__: 63 | :kbd:`n` next, 64 | :kbd:`p` previous, 65 | :kbd:`u` up (= to the parent page), 66 | :kbd:`i` index, 67 | :kbd:`s` search and 68 | :kbd:`m` menu (= open/close sidebar). 69 | 70 | __ https://developer.mozilla.org/en-US/docs/ 71 | Web/HTML/Global_attributes/accesskey 72 | 73 | Click on the `hamburger button`__ in the topbar 74 | to open and close the sidebar. 75 | The width of the sidebar can be adjusted by dragging its border. 76 | Click on the title in the topbar to scroll to the top of the page, 77 | if already at the top, go "up" to the parent page 78 | (eventually ending up on this very page). 79 | 80 | __ https://en.wikipedia.org/wiki/Hamburger_button 81 | 82 | On *touch-enabled* devices: 83 | Tap at the top of the page to show the topbar (if it was scrolled away); 84 | swipe from the left edge to show the sidebar, 85 | swipe towards the left to hide it. 86 | -------------------------------------------------------------------------------- /doc/installation.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Installation\n", 17 | "\n", 18 | "Note that some packages may be out of date.\n", 19 | "You can always get the newest `nbsphinx` release from [PyPI](https://pypi.org/project/nbsphinx) (using `pip`).\n", 20 | "If you want to try the latest development version, have a look at the section [Contributing](contributing.rst).\n", 21 | "\n", 22 | "## `nbsphinx` Packages\n", 23 | "\n", 24 | "[![Anaconda Badge](https://anaconda.org/conda-forge/nbsphinx/badges/version.svg)](https://anaconda.org/conda-forge/nbsphinx)\n", 25 | "\n", 26 | "If you are using the `conda` package manager\n", 27 | "(e.g. with\n", 28 | "[Miniforge](https://github.com/conda-forge/miniforge) or\n", 29 | "[Miniconda](https://docs.conda.io/en/latest/miniconda.html)),\n", 30 | "you can install `nbsphinx` from the [conda-forge](https://conda-forge.org/) channel:\n", 31 | "\n", 32 | " conda install -c conda-forge nbsphinx\n", 33 | "\n", 34 | "[![PyPI version](https://badge.fury.io/py/nbsphinx.png)](https://pypi.org/project/nbsphinx)\n", 35 | "\n", 36 | "You can of course also install `nbsphinx` with `pip`, Python's own package manager:\n", 37 | "\n", 38 | " python3 -m pip install nbsphinx\n", 39 | "\n", 40 | "Depending on your Python installation,\n", 41 | "you may have to use `python` instead of `python3`.\n", 42 | "If you have installed the module already,\n", 43 | "you can use the `--upgrade` flag to get the newest release.\n", 44 | "\n", 45 | "There are more packages available.\n", 46 | "For an overview, see\n", 47 | "[repology](https://repology.org/project/python:nbsphinx/versions)." 48 | ] 49 | }, 50 | { 51 | "cell_type": "markdown", 52 | "metadata": {}, 53 | "source": [ 54 | "## `nbsphinx` Prerequisites\n", 55 | "\n", 56 | "Some of the aforementioned packages will install some of these prerequisites automatically, some of the things may be already installed on your computer anyway.\n", 57 | "\n", 58 | "### Python\n", 59 | "\n", 60 | "Of course you'll need Python, because both Sphinx and `nbsphinx` are implemented in Python.\n", 61 | "There are many ways to get Python.\n", 62 | "If you don't know which one is best for you, you can try [Miniforge](https://github.com/conda-forge/miniforge).\n", 63 | "\n", 64 | "### Sphinx\n", 65 | "\n", 66 | "You'll need [Sphinx](https://www.sphinx-doc.org/) as well, because `nbsphinx` is just a Sphinx extension and doesn't do anything on its own.\n", 67 | "\n", 68 | "If you use `conda`, you can get [Sphinx from the conda-forge channel](https://anaconda.org/conda-forge/sphinx):\n", 69 | "\n", 70 | " conda install -c conda-forge sphinx\n", 71 | "\n", 72 | "Alternatively, you can install it with `pip` (see below):\n", 73 | "\n", 74 | " python3 -m pip install Sphinx\n", 75 | "\n", 76 | "### pip\n", 77 | "\n", 78 | "Recent versions of Python already come with `pip` pre-installed.\n", 79 | "If you don't have it, you can [install it manually](https://pip.pypa.io/en/latest/installing/).\n", 80 | "\n", 81 | "### pandoc\n", 82 | "\n", 83 | "The stand-alone program [pandoc](https://pandoc.org/) is used to convert Markdown content to something Sphinx can understand. You have to install this program separately, ideally with your package manager. If you are using `conda`, you can install [pandoc from the conda-forge channel](https://anaconda.org/conda-forge/pandoc):\n", 84 | "\n", 85 | " conda install -c conda-forge pandoc\n", 86 | "\n", 87 | "If that doesn't work out for you, have a look at `pandoc`'s [installation instructions](https://pandoc.org/installing.html).\n", 88 | "\n", 89 | "
\n", 90 | "\n", 91 | "Note\n", 92 | "\n", 93 | "The use of `pandoc` in `nbsphinx` is temporary, but will likely stay that way for a long time, see [issue #36](https://github.com/spatialaudio/nbsphinx/issues/36).\n", 94 | "\n", 95 | "
\n", 96 | "\n", 97 | "### Pygments Lexer for Syntax Highlighting\n", 98 | "\n", 99 | "To get proper syntax highlighting in code cells, you'll need an appropriate *Pygments lexer*.\n", 100 | "This of course depends on the programming language of your Jupyter notebooks (more specifically, the `pygments_lexer` metadata of your notebooks).\n", 101 | "\n", 102 | "For example, if you use Python in your notebooks, you'll have to have the `IPython` package installed, e.g. with\n", 103 | "\n", 104 | " conda install -c conda-forge ipython\n", 105 | "\n", 106 | "or\n", 107 | "\n", 108 | " python3 -m pip install IPython\n", 109 | "\n", 110 | "
\n", 111 | "\n", 112 | "Note\n", 113 | "\n", 114 | "If you are using Anaconda with the default channel and syntax highlighting in code cells doesn't seem to work,\n", 115 | "you can try to install IPython from the `conda-forge` channel or directly with `pip`, or as a work-around,\n", 116 | "add `'IPython.sphinxext.ipython_console_highlighting'` to `extensions` in your `conf.py`.\n", 117 | "\n", 118 | "For details, see [Anaconda issue #1430](https://github.com/ContinuumIO/anaconda-issues/issues/1430) and\n", 119 | "[nbsphinx issue #24](https://github.com/spatialaudio/nbsphinx/issues/24).\n", 120 | "\n", 121 | "
\n", 122 | "\n", 123 | "### Jupyter Kernel\n", 124 | "\n", 125 | "If you want to execute your notebooks during the Sphinx build process (see [Controlling Notebook Execution](executing-notebooks.ipynb)), you need an appropriate [Jupyter kernel](https://jupyter.readthedocs.io/en/latest/projects/kernels.html) installed.\n", 126 | "\n", 127 | "For example, if you use Python, you should install the `ipykernel` package, e.g. with\n", 128 | "\n", 129 | " conda install -c conda-forge ipykernel\n", 130 | "\n", 131 | "or\n", 132 | "\n", 133 | " python3 -m pip install ipykernel\n", 134 | "\n", 135 | "If you created your notebooks yourself with Jupyter, it's very likely that you have the right kernel installed already.\n", 136 | "\n", 137 | "
\n", 138 | "\n", 139 | "Note\n", 140 | "\n", 141 | "If your [automatic builds](usage.ipynb#Automatic-Creation-of-HTML-and-PDF-output-on-readthedocs.org) on https://readthedocs.org are failing due to an error like the one below, add `ipykernel` to `docs/requirements.txt` or `doc/environment.yml` to resolve.\n", 142 | "\n", 143 | "```\n", 144 | "jupyter_client.kernelspec.nosuchkernel: no such kernel named python3\n", 145 | "```\n", 146 | "\n", 147 | "
\n" 148 | ] 149 | } 150 | ], 151 | "metadata": { 152 | "kernelspec": { 153 | "display_name": "Python 3 (ipykernel)", 154 | "language": "python", 155 | "name": "python3" 156 | }, 157 | "language_info": { 158 | "codemirror_mode": { 159 | "name": "ipython", 160 | "version": 3 161 | }, 162 | "file_extension": ".py", 163 | "mimetype": "text/x-python", 164 | "name": "python", 165 | "nbconvert_exporter": "python", 166 | "pygments_lexer": "ipython3", 167 | "version": "3.11.1" 168 | } 169 | }, 170 | "nbformat": 4, 171 | "nbformat_minor": 4 172 | } 173 | -------------------------------------------------------------------------------- /doc/links.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# External Links" 17 | ] 18 | }, 19 | { 20 | "cell_type": "markdown", 21 | "metadata": {}, 22 | "source": [ 23 | "**nbconvert**\n", 24 | "\n", 25 | "The official conversion tool of the Jupyter project.\n", 26 | "It can be used to convert notebooks to HTML, LaTeX and many other formats.\n", 27 | "\n", 28 | "Its `--execute` flag can be used to automatically execute notebooks before conversion.\n", 29 | "\n", 30 | "https://nbconvert.readthedocs.io/\n", 31 | "\n", 32 | "https://github.com/jupyter/nbconvert" 33 | ] 34 | }, 35 | { 36 | "cell_type": "markdown", 37 | "metadata": {}, 38 | "source": [ 39 | "**RunNotebook (notebook_sphinxext.py)**\n", 40 | "\n", 41 | "Notebooks can be included in `*.rst` files with a custom `notebook` directive.\n", 42 | "Uses `nbconvert` to execute notebooks and to convert the result to HTML.\n", 43 | "\n", 44 | "No LaTeX support.\n", 45 | "\n", 46 | "https://github.com/ngoldbaum/RunNotebook\n", 47 | "\n", 48 | "There are some forks:\n", 49 | "\n", 50 | "* `https://bitbucket.org/yt_analysis/yt-doc/src/default/extensions/notebook_sphinxext.py` (not available anymore)\n", 51 | "* https://github.com/matthew-brett/perrin-academy/blob/master/sphinxext/notebook_sphinxext.py" 52 | ] 53 | }, 54 | { 55 | "cell_type": "markdown", 56 | "metadata": {}, 57 | "source": [ 58 | "**nbsite**\n", 59 | "\n", 60 | "Build a tested, sphinx-based website from notebooks.\n", 61 | "\n", 62 | "https://nbsite.holoviz.org/" 63 | ] 64 | }, 65 | { 66 | "cell_type": "markdown", 67 | "metadata": {}, 68 | "source": [ 69 | "**ipypublish**\n", 70 | "\n", 71 | "A workflow for creating and editing publication ready scientific reports and presentations, from one or more Jupyter Notebooks, without leaving the browser!\n", 72 | "\n", 73 | "https://ipypublish.readthedocs.io/\n", 74 | "\n", 75 | "https://github.com/chrisjsewell/ipypublish" 76 | ] 77 | }, 78 | { 79 | "cell_type": "markdown", 80 | "metadata": {}, 81 | "source": [ 82 | "**jupyterbook**\n", 83 | "\n", 84 | "Jupyter Book is an open source project for building beautiful, publication-quality books and documents from computational material.\n", 85 | "\n", 86 | "https://jupyterbook.org/\n", 87 | "\n", 88 | "https://github.com/executablebooks/jupyter-book" 89 | ] 90 | }, 91 | { 92 | "cell_type": "markdown", 93 | "metadata": {}, 94 | "source": [ 95 | "**MyST-NB**\n", 96 | "\n", 97 | "A collection of tools for working with Jupyter Notebooks in Sphinx.\n", 98 | "\n", 99 | "The primary tool this package provides is a Sphinx parser for `ipynb` files.\n", 100 | "This allows you to directly convert Jupyter Notebooks into Sphinx documents.\n", 101 | "It relies heavily on the\n", 102 | "[MyST parser](https://github.com/executablebooks/MyST-Parser).\n", 103 | "\n", 104 | "https://myst-nb.readthedocs.io/\n", 105 | "\n", 106 | "https://github.com/executablebooks/MyST-NB" 107 | ] 108 | }, 109 | { 110 | "cell_type": "markdown", 111 | "metadata": {}, 112 | "source": [ 113 | "**notebook-to-pdf**\n", 114 | "\n", 115 | "This Jupyter notebook extension allows you to save your notebook as a PDF.\n", 116 | "\n", 117 | "Three new features compared to the official \"save as PDF\" extension:\n", 118 | "\n", 119 | "1. produce a PDF with the smallest number of page breaks,\n", 120 | "1. the original notebook is attached to the PDF; and\n", 121 | "1. this extension does not require LaTex.\n", 122 | "\n", 123 | "https://github.com/betatim/notebook-as-pdf" 124 | ] 125 | }, 126 | { 127 | "cell_type": "markdown", 128 | "metadata": {}, 129 | "source": [ 130 | "**nbinteract**\n", 131 | "\n", 132 | "Create interactive webpages from Jupyter Notebooks\n", 133 | "\n", 134 | "https://www.samlau.me/nbinteract/\n", 135 | "\n", 136 | "https://github.com/SamLau95/nbinteract" 137 | ] 138 | }, 139 | { 140 | "cell_type": "markdown", 141 | "metadata": {}, 142 | "source": [ 143 | "**nb_pdf_template**\n", 144 | "\n", 145 | "An extended `nbconvert` template for LaTeX output.\n", 146 | "\n", 147 | "https://github.com/t-makaro/nb_pdf_template" 148 | ] 149 | }, 150 | { 151 | "cell_type": "markdown", 152 | "metadata": {}, 153 | "source": [ 154 | "**nb2plots**\n", 155 | "\n", 156 | "Notebook to reStructuredText converter which uses a modified version of the matplotlib `plot` directive.\n", 157 | "\n", 158 | "https://github.com/matthew-brett/nb2plots" 159 | ] 160 | }, 161 | { 162 | "cell_type": "markdown", 163 | "metadata": {}, 164 | "source": [ 165 | "**brole**\n", 166 | "\n", 167 | "A Sphinx role for IPython notebooks\n", 168 | "\n", 169 | "https://github.com/matthew-brett/brole" 170 | ] 171 | }, 172 | { 173 | "cell_type": "markdown", 174 | "metadata": {}, 175 | "source": [ 176 | "**Sphinx-Gallery**\n", 177 | "\n", 178 | "https://sphinx-gallery.readthedocs.io/" 179 | ] 180 | }, 181 | { 182 | "cell_type": "markdown", 183 | "metadata": {}, 184 | "source": [ 185 | "**sphinx-nbexamples**\n", 186 | "\n", 187 | "https://sphinx-nbexamples.readthedocs.io/\n", 188 | "\n", 189 | "https://github.com/Chilipp/sphinx-nbexamples" 190 | ] 191 | }, 192 | { 193 | "cell_type": "markdown", 194 | "metadata": {}, 195 | "source": [ 196 | "**nbsphinx-link**\n", 197 | "\n", 198 | "https://github.com/vidartf/nbsphinx-link\n", 199 | "\n", 200 | "Uses `nbsphinx`, but supports notebooks outside the Sphinx source directory.\n", 201 | "\n", 202 | "See https://github.com/spatialaudio/nbsphinx/pull/33 for some limitations." 203 | ] 204 | }, 205 | { 206 | "cell_type": "markdown", 207 | "metadata": {}, 208 | "source": [ 209 | "**bookbook**\n", 210 | "\n", 211 | "Uses `nbconvert` to create a sequence of HTML or\n", 212 | "a concatenated LaTeX file from a sequence of notebooks.\n", 213 | "\n", 214 | "https://github.com/takluyver/bookbook" 215 | ] 216 | }, 217 | { 218 | "cell_type": "markdown", 219 | "metadata": {}, 220 | "source": [ 221 | "**jupyter-sphinx**\n", 222 | "\n", 223 | "Jupyter Sphinx is a Sphinx extension that executes embedded code in a Jupyter kernel, and embeds outputs of that code in the output document. It has support for rich output such as images, Latex math and even javascript widgets.\n", 224 | "\n", 225 | "https://jupyter-sphinx.readthedocs.io/\n", 226 | "\n", 227 | "https://github.com/jupyter/jupyter-sphinx" 228 | ] 229 | }, 230 | { 231 | "cell_type": "markdown", 232 | "metadata": {}, 233 | "source": [ 234 | "**DocOnce**\n", 235 | "\n", 236 | "http://hplgit.github.io/doconce/doc/web/index.html" 237 | ] 238 | }, 239 | { 240 | "cell_type": "markdown", 241 | "metadata": {}, 242 | "source": [ 243 | "**Quarto**\n", 244 | "\n", 245 | "Open-source scientific and technical publishing system built on Pandoc.\n", 246 | "\n", 247 | "https://github.com/quarto-dev/quarto-cli" 248 | ] 249 | }, 250 | { 251 | "cell_type": "markdown", 252 | "metadata": {}, 253 | "source": [ 254 | "**Converting Notebooks to reStructuredText**\n", 255 | "\n", 256 | "https://github.com/perrette/dimarray/blob/master/docs/scripts/nbconvert_to_rst.py\n", 257 | "\n", 258 | "`https://gist.github.com/hadim/16e29b5848672e2e497c` (not available anymore)\n", 259 | "\n", 260 | "https://sphinx-ipynb.readthedocs.io/" 261 | ] 262 | }, 263 | { 264 | "cell_type": "markdown", 265 | "metadata": {}, 266 | "source": [ 267 | "**Converting reStructuredText to Notebooks**\n", 268 | "\n", 269 | "https://github.com/nthiery/rst-to-ipynb\n", 270 | "\n", 271 | "https://github.com/QuantEcon/sphinxcontrib-jupyter" 272 | ] 273 | }, 274 | { 275 | "cell_type": "markdown", 276 | "metadata": {}, 277 | "source": [ 278 | "**Converting Notebooks to HTML for Blog Posts**\n", 279 | "\n", 280 | "http://dongweiming.github.io/divingintoipynb_nikola/posts/nbconvert.html\n", 281 | "\n", 282 | "https://github.com/getpelican/pelican-plugins/blob/master/liquid_tags/notebook.py" 283 | ] 284 | }, 285 | { 286 | "cell_type": "markdown", 287 | "metadata": {}, 288 | "source": [ 289 | "**Further Posts and Issues**\n", 290 | "\n", 291 | "https://github.com/ipython/ipython/issues/4936\n", 292 | "\n", 293 | "`https://mail.scipy.org/pipermail/ipython-user/2013-December/013490.html` (not available anymore)" 294 | ] 295 | } 296 | ], 297 | "metadata": { 298 | "kernelspec": { 299 | "display_name": "Python 3", 300 | "language": "python", 301 | "name": "python3" 302 | }, 303 | "language_info": { 304 | "codemirror_mode": { 305 | "name": "ipython", 306 | "version": 3 307 | }, 308 | "file_extension": ".py", 309 | "mimetype": "text/x-python", 310 | "name": "python", 311 | "nbconvert_exporter": "python", 312 | "pygments_lexer": "ipython3", 313 | "version": "3.8.6" 314 | } 315 | }, 316 | "nbformat": 4, 317 | "nbformat_minor": 4 318 | } 319 | -------------------------------------------------------------------------------- /doc/matplotlibrc: -------------------------------------------------------------------------------- 1 | figure.dpi: 96 2 | -------------------------------------------------------------------------------- /doc/never-execute.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Explicitly Dis-/Enabling Notebook Execution\n", 17 | "\n", 18 | "If you want to include a notebook without outputs and yet don't want `nbsphinx` to execute it for you, you can explicitly disable this feature.\n", 19 | "\n", 20 | "You can do this globally by setting the following option in [conf.py](conf.py):\n", 21 | "\n", 22 | "```python\n", 23 | "nbsphinx_execute = 'never'\n", 24 | "```\n", 25 | "\n", 26 | "Or on a per-notebook basis by adding this to the notebook's JSON metadata:\n", 27 | "\n", 28 | "```\n", 29 | "\"nbsphinx\": {\n", 30 | " \"execute\": \"never\"\n", 31 | "},\n", 32 | "```\n", 33 | "\n", 34 | "There are three possible settings, `\"always\"`, `\"auto\"` and `\"never\"`.\n", 35 | "By default (= `\"auto\"`), notebooks with no outputs are executed and notebooks with at least one output are not.\n", 36 | "As always, per-notebook settings take precedence over the settings in `conf.py`.\n", 37 | "\n", 38 | "This very notebook has its metadata set to `\"never\"`, therefore the following cell is not executed:" 39 | ] 40 | }, 41 | { 42 | "cell_type": "code", 43 | "execution_count": null, 44 | "metadata": {}, 45 | "outputs": [], 46 | "source": [ 47 | "6 * 7" 48 | ] 49 | } 50 | ], 51 | "metadata": { 52 | "kernelspec": { 53 | "display_name": "Python 3", 54 | "language": "python", 55 | "name": "python3" 56 | }, 57 | "language_info": { 58 | "codemirror_mode": { 59 | "name": "ipython", 60 | "version": 3 61 | }, 62 | "file_extension": ".py", 63 | "mimetype": "text/x-python", 64 | "name": "python", 65 | "nbconvert_exporter": "python", 66 | "pygments_lexer": "ipython3", 67 | "version": "3.6.7" 68 | }, 69 | "nbsphinx": { 70 | "execute": "never" 71 | } 72 | }, 73 | "nbformat": 4, 74 | "nbformat_minor": 2 75 | } 76 | -------------------------------------------------------------------------------- /doc/orphan.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# An Orphan Notebook (HTML Only)\n", 17 | "\n", 18 | "This means that it doesn't appear in a [toctree](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree) (see `index.rst`), but other pages can still link to it ...\n", 19 | "\n", 20 | "* ... from a [Markdown cell of another notebook](markdown-cells.ipynb#Links-to-Other-Notebooks) using\n", 21 | "\n", 22 | " ```\n", 23 | " [some link text](notebookname.ipynb)\n", 24 | " ```\n", 25 | "\n", 26 | "* ... from a [reST page](a-normal-rst-file.rst#links-to-notebooks-and-other-sphinx-source-files) using\n", 27 | "\n", 28 | " ```rst\n", 29 | " `some link text `_\n", 30 | " ```\n", 31 | "\n", 32 | "Sphinx raises a warning in case of orphaned documents:\n", 33 | "\n", 34 | " WARNING: document isn't included in any toctree\n", 35 | "\n", 36 | "If you want to avoid this warning, you can add this to the notebook's JSON metadata:\n", 37 | "\n", 38 | "```\n", 39 | "\"nbsphinx\": {\n", 40 | " \"orphan\": true\n", 41 | "},\n", 42 | "```\n", 43 | "\n", 44 | "
\n", 45 | "\n", 46 | "**Note:**\n", 47 | "\n", 48 | "Orphan notebooks are not included in the LaTeX output!\n", 49 | "\n", 50 | "
\n", 51 | "\n", 52 | "[Back to main page](index.rst)" 53 | ] 54 | } 55 | ], 56 | "metadata": { 57 | "kernelspec": { 58 | "display_name": "Python 3", 59 | "language": "python", 60 | "name": "python3" 61 | }, 62 | "language_info": { 63 | "codemirror_mode": { 64 | "name": "ipython", 65 | "version": 3 66 | }, 67 | "file_extension": ".py", 68 | "mimetype": "text/x-python", 69 | "name": "python", 70 | "nbconvert_exporter": "python", 71 | "pygments_lexer": "ipython3", 72 | "version": "3.6.7" 73 | }, 74 | "nbsphinx": { 75 | "orphan": true 76 | } 77 | }, 78 | "nbformat": 4, 79 | "nbformat_minor": 2 80 | } 81 | -------------------------------------------------------------------------------- /doc/pre-executed.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Pre-Executing Notebooks\n", 17 | "\n", 18 | "Automatically executing notebooks during the Sphinx build process is an important feature of `nbsphinx`.\n", 19 | "However, there are a few use cases where pre-executing a notebook and storing the outputs might be preferable.\n", 20 | "Storing any output will, by default, stop ``nbsphinx`` from executing the notebook." 21 | ] 22 | }, 23 | { 24 | "cell_type": "markdown", 25 | "metadata": {}, 26 | "source": [ 27 | "## Long-Running Cells\n", 28 | "\n", 29 | "If you are doing some very time-consuming computations, it might not be feasible to re-execute the notebook every time you build your Sphinx documentation.\n", 30 | "\n", 31 | "So just do it once -- when you happen to have the time -- and then just keep the output." 32 | ] 33 | }, 34 | { 35 | "cell_type": "code", 36 | "execution_count": 1, 37 | "metadata": {}, 38 | "outputs": [], 39 | "source": [ 40 | "import time" 41 | ] 42 | }, 43 | { 44 | "cell_type": "code", 45 | "execution_count": 2, 46 | "metadata": {}, 47 | "outputs": [ 48 | { 49 | "name": "stdout", 50 | "output_type": "stream", 51 | "text": [ 52 | "CPU times: user 160 ms, sys: 56 ms, total: 216 ms\n", 53 | "Wall time: 1h 1s\n" 54 | ] 55 | }, 56 | { 57 | "data": { 58 | "text/plain": [ 59 | "42" 60 | ] 61 | }, 62 | "execution_count": 2, 63 | "metadata": {}, 64 | "output_type": "execute_result" 65 | } 66 | ], 67 | "source": [ 68 | "%time time.sleep(60 * 60)\n", 69 | "6 * 7" 70 | ] 71 | }, 72 | { 73 | "cell_type": "markdown", 74 | "metadata": {}, 75 | "source": [ 76 | "## Rare Libraries\n", 77 | "\n", 78 | "You might have created results with a library that's hard to install and therefore you have only managed to install it on one very old computer in the basement, so you probably cannot run this whenever you build your Sphinx docs." 79 | ] 80 | }, 81 | { 82 | "cell_type": "code", 83 | "execution_count": 3, 84 | "metadata": {}, 85 | "outputs": [], 86 | "source": [ 87 | "from a_very_rare_library import calculate_the_answer" 88 | ] 89 | }, 90 | { 91 | "cell_type": "code", 92 | "execution_count": 4, 93 | "metadata": {}, 94 | "outputs": [ 95 | { 96 | "data": { 97 | "text/plain": [ 98 | "42" 99 | ] 100 | }, 101 | "execution_count": 4, 102 | "metadata": {}, 103 | "output_type": "execute_result" 104 | } 105 | ], 106 | "source": [ 107 | "calculate_the_answer()" 108 | ] 109 | }, 110 | { 111 | "cell_type": "markdown", 112 | "metadata": {}, 113 | "source": [ 114 | "## Exceptions\n", 115 | "\n", 116 | "If an exception is raised during the Sphinx build process, it is stopped (the build process, not the exception!).\n", 117 | "If you want to show to your audience how an exception looks like, you have two choices:\n", 118 | "\n", 119 | "1. Allow errors -- either generally or on a per-notebook or per-cell basis -- see [Ignoring Errors](allow-errors.ipynb) ([per cell](allow-errors-per-cell.ipynb)).\n", 120 | "\n", 121 | "1. Execute the notebook beforehand and save the results, like it's done in this example notebook:" 122 | ] 123 | }, 124 | { 125 | "cell_type": "code", 126 | "execution_count": 5, 127 | "metadata": {}, 128 | "outputs": [ 129 | { 130 | "ename": "ZeroDivisionError", 131 | "evalue": "division by zero", 132 | "output_type": "error", 133 | "traceback": [ 134 | "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m", 135 | "\u001b[0;31mZeroDivisionError\u001b[0m Traceback (most recent call last)", 136 | "\u001b[0;32m\u001b[0m in \u001b[0;36m\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0;36m1\u001b[0m \u001b[0;34m/\u001b[0m \u001b[0;36m0\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m", 137 | "\u001b[0;31mZeroDivisionError\u001b[0m: division by zero" 138 | ] 139 | } 140 | ], 141 | "source": [ 142 | "1 / 0" 143 | ] 144 | }, 145 | { 146 | "cell_type": "markdown", 147 | "metadata": {}, 148 | "source": [ 149 | "## Client-specific Outputs\n", 150 | "\n", 151 | "When `nbsphinx` executes notebooks,\n", 152 | "it uses the `nbconvert` module to do so.\n", 153 | "Certain Jupyter clients might produce output\n", 154 | "that differs from what `nbconvert` would produce.\n", 155 | "To preserve those original outputs,\n", 156 | "the notebook has to be executed and saved\n", 157 | "before running Sphinx.\n", 158 | "\n", 159 | "For example,\n", 160 | "the JupyterLab help system shows the help text as cell outputs,\n", 161 | "while executing with `nbconvert` doesn't produce any output." 162 | ] 163 | }, 164 | { 165 | "cell_type": "code", 166 | "execution_count": 6, 167 | "metadata": {}, 168 | "outputs": [ 169 | { 170 | "data": { 171 | "text/plain": [ 172 | "\u001b[0;31mSignature:\u001b[0m \u001b[0msorted\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0miterable\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m/\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m*\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mkey\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0;32mNone\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mreverse\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0;32mFalse\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n", 173 | "\u001b[0;31mDocstring:\u001b[0m\n", 174 | "Return a new list containing all items from the iterable in ascending order.\n", 175 | "\n", 176 | "A custom key function can be supplied to customize the sort order, and the\n", 177 | "reverse flag can be set to request the result in descending order.\n", 178 | "\u001b[0;31mType:\u001b[0m builtin_function_or_method\n" 179 | ] 180 | }, 181 | "metadata": {}, 182 | "output_type": "display_data" 183 | } 184 | ], 185 | "source": [ 186 | "sorted?" 187 | ] 188 | }, 189 | { 190 | "cell_type": "markdown", 191 | "metadata": {}, 192 | "source": [ 193 | "## Interactive Input\n", 194 | "\n", 195 | "If your code asks for user input,\n", 196 | "it probably doesn't work when executed by Sphinx/`nbsphinx`.\n", 197 | "You'll probably get an error like this:\n", 198 | "\n", 199 | " StdinNotImplementedError: raw_input was called, but this frontend does not support input requests.\n", 200 | "\n", 201 | "In this case, you can run the notebook interactively,\n", 202 | "provide the desired inputs and then save the notebook including its cell outputs." 203 | ] 204 | }, 205 | { 206 | "cell_type": "code", 207 | "execution_count": 7, 208 | "metadata": {}, 209 | "outputs": [ 210 | { 211 | "name": "stdin", 212 | "output_type": "stream", 213 | "text": [ 214 | "What... is your name? Sir Lancelot of Camelot\n", 215 | "What... is your quest? To seek the Holy Grail\n", 216 | "What... is your favorite color? Blue\n" 217 | ] 218 | } 219 | ], 220 | "source": [ 221 | "name = input('What... is your name?')\n", 222 | "quest = input('What... is your quest?')\n", 223 | "color = input('What... is your favorite color?')" 224 | ] 225 | } 226 | ], 227 | "metadata": { 228 | "kernelspec": { 229 | "display_name": "Python 3", 230 | "language": "python", 231 | "name": "python3" 232 | }, 233 | "language_info": { 234 | "codemirror_mode": { 235 | "name": "ipython", 236 | "version": 3 237 | }, 238 | "file_extension": ".py", 239 | "mimetype": "text/x-python", 240 | "name": "python", 241 | "nbconvert_exporter": "python", 242 | "pygments_lexer": "ipython3", 243 | "version": "3.8.6" 244 | }, 245 | "widgets": { 246 | "state": {}, 247 | "version": "0.2.0" 248 | } 249 | }, 250 | "nbformat": 4, 251 | "nbformat_minor": 4 252 | } 253 | -------------------------------------------------------------------------------- /doc/prolog-and-epilog.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Prolog and Epilog\n", 17 | "\n", 18 | "When including notebooks in your Sphinx documentation, you can choose to add some generic content before and after each notebook.\n", 19 | "This can be done with the configuration values `nbsphinx_prolog` and `nbsphinx_epilog` in the file `conf.py`.\n", 20 | "\n", 21 | "The prolog and epilog strings can hold arbitrary [reST](https://www.sphinx-doc.org/rest.html) markup.\n", 22 | "Particularly, the [only](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-only) and [raw](https://docutils.sourceforge.io/docs/ref/rst/directives.html#raw-data-pass-through) directives can be used to have different content for HTML and LaTeX output.\n", 23 | "\n", 24 | "Those strings are also processed by the [Jinja2](https://jinja.palletsprojects.com/) templating engine.\n", 25 | "This means you can run Python-like code within those strings.\n", 26 | "You have access to the current [Sphinx build environment](https://www.sphinx-doc.org/en/master/extdev/envapi.html) via the variable `env`.\n", 27 | "Most notably, you can get the file name of the current notebook with\n", 28 | "\n", 29 | " {{ env.doc2path(env.docname, base=None)|string }}\n", 30 | "\n", 31 | "Have a look at the [Jinja2 template documentation](https://jinja.palletsprojects.com/templates/) for more information.\n", 32 | "\n", 33 | "
\n", 34 | "\n", 35 | "Warning\n", 36 | "\n", 37 | "If you use invalid syntax, you might get an error like this:\n", 38 | "\n", 39 | " jinja2.exceptions.TemplateSyntaxError: expected token ':', got '}'\n", 40 | "\n", 41 | "This is especially prone to happen when using raw LaTeX, with its abundance of braces.\n", 42 | "To avoid clashing braces you can try to insert additional spaces or LaTeX macros that don't have a visible effect, like e.g. `\\strut{}`.\n", 43 | "For example, you can avoid three consecutive opening braces with something like that:\n", 44 | "\n", 45 | " \\texttt{\\strut{}{{ env.doc2path(env.docname, base=None)|string }}}\n", 46 | "\n", 47 | "NB: The three consecutive closing braces in this example are not problematic.\n", 48 | " \n", 49 | "An alternative work-around would be to surround LaTeX braces with Jinja braces like this:\n", 50 | " \n", 51 | " {{ '{' }}\n", 52 | " \n", 53 | "The string within will not be touched by Jinja.\n", 54 | "\n", 55 | "Another special Jinja syntax is `{%`, which is also often used in fancy TeX/LaTeX code.\n", 56 | "A work-around for this situation would be to use\n", 57 | " \n", 58 | " {{ '{%' }}\n", 59 | "\n", 60 | "
" 61 | ] 62 | }, 63 | { 64 | "cell_type": "markdown", 65 | "metadata": {}, 66 | "source": [ 67 | "## Examples\n", 68 | "\n", 69 | "You can include a simple static string, using [reST](https://www.sphinx-doc.org/rest.html) markup if you like:\n", 70 | "\n", 71 | "```python\n", 72 | "nbsphinx_epilog = \"\"\"\n", 73 | "----\n", 74 | "\n", 75 | "Generated by nbsphinx_ from a Jupyter_ notebook.\n", 76 | "\n", 77 | ".. _nbsphinx: https://nbsphinx.readthedocs.io/\n", 78 | ".. _Jupyter: https://jupyter.org/\n", 79 | "\"\"\"\n", 80 | "```\n", 81 | "\n", 82 | "Using some additional Jinja2 markup and the information from the `env` variable, you can create URLs that point to the current notebook file, but located on some other server:\n", 83 | "\n", 84 | "```python\n", 85 | "nbsphinx_prolog = \"\"\"\n", 86 | "Go there: https://example.org/notebooks/{{ env.doc2path(env.docname, base=None)|string }}\n", 87 | "\n", 88 | "----\n", 89 | "\"\"\"\n", 90 | "```\n", 91 | "\n", 92 | "You can also use separate content for HTML and LaTeX output, e.g.:\n", 93 | "\n", 94 | "```python\n", 95 | "nbsphinx_prolog = r\"\"\"\n", 96 | "{% set docname = env.doc2path(env.docname, base=None)|string %}\n", 97 | "\n", 98 | ".. only:: html\n", 99 | "\n", 100 | " Go there: https://example.org/notebooks/{{ docname }}\n", 101 | "\n", 102 | ".. raw:: latex\n", 103 | "\n", 104 | " \\nbsphinxstartnotebook{The following section was created from\n", 105 | " \\texttt{\\strut{}{{ docname }}}:}\n", 106 | "\"\"\"\n", 107 | "\n", 108 | "nbsphinx_epilog = r\"\"\"\n", 109 | ".. raw:: latex\n", 110 | "\n", 111 | " \\nbsphinxstopnotebook{\\hfill End of notebook.}\n", 112 | "\"\"\"\n", 113 | "```\n", 114 | "\n", 115 | "Note the use of the `\\nbsphinxstartnotebook` and `\\nbsphinxstopnotebook` commands.\n", 116 | "Those make sure there is not too much space between the \"prolog\" and the beginning of the notebook and, respectively, between the end of the notebook and the \"epilog\".\n", 117 | "They also avoid page breaks, in order for the \"prolog\"/\"epilog\" not to end up on the page before/after the notebook.\n", 118 | "\n", 119 | "For a more involved example for different HTML and LaTeX versions, see the file [conf.py](conf.py) of the `nbsphinx` documentation." 120 | ] 121 | } 122 | ], 123 | "metadata": { 124 | "kernelspec": { 125 | "display_name": "Python 3", 126 | "language": "python", 127 | "name": "python3" 128 | }, 129 | "language_info": { 130 | "codemirror_mode": { 131 | "name": "ipython", 132 | "version": 3 133 | }, 134 | "file_extension": ".py", 135 | "mimetype": "text/x-python", 136 | "name": "python", 137 | "nbconvert_exporter": "python", 138 | "pygments_lexer": "ipython3", 139 | "version": "3.6.7" 140 | } 141 | }, 142 | "nbformat": 4, 143 | "nbformat_minor": 2 144 | } 145 | -------------------------------------------------------------------------------- /doc/raw-cells.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Raw Cells\n", 17 | "\n", 18 | "Any Jupyter Notebook consists of cells of three different types:\n", 19 | "[Code cells](./code-cells.ipynb),\n", 20 | "[Markdown cells](./markdown-cells.ipynb)\n", 21 | ", and/or Raw cells.\n", 22 | "While most Jupyter Notebook users are very familiar with Code cells and Markdown cells in Jupyter Notebooks, Raw cells are less frequently used.\n", 23 | "For Jupyter Notebook, they are introduced\n", 24 | "[here](https://jupyter-notebook.readthedocs.io/en/stable/notebook.html?highlight=raw#raw-cells)\n", 25 | "and for JupyterLab\n", 26 | "[here](https://jupyterlab.readthedocs.io/en/stable/extension/notebook.html?highlight=raw#model).\n", 27 | "The Raw cells are also sometimes referred to as Raw NBConvert cells in the context of\n", 28 | "[nbconvert](https://nbconvert.readthedocs.io/en/latest/architecture.html?highlight=raw#a-detailed-pipeline-exploration).\n", 29 | "The Raw cell type can be used to render different code formats into HTML or LaTeX by Sphinx.\n", 30 | "This information is stored in the notebook metadata and converted appropriately.\n", 31 | "\n", 32 | "## Usage\n", 33 | "\n", 34 | "Raw cells are created differently depending on the user interface.\n", 35 | "\n", 36 | "### Jupyter Notebook\n", 37 | "\n", 38 | "To select a desired format from within Jupyter Notebook, select the cell containing your special code and choose options from the following dropdown menus:\n", 39 | "\n", 40 | "1. Select \"Raw NBConvert\" in the Menu Toolbar (just below the two menus \"Widgets\" and \"Help\").\n", 41 | "2. Click on the \"Raw NBConvert Format\" dropdown menu within the cell and select \"reST\".\n", 42 | "\n", 43 | "![Steps for converting cells to Raw formats in Jupyter Notebook](images/raw_cells_jupyter_notebook.png)\n", 44 | "\n", 45 | "\n", 46 | "### JupyterLab\n", 47 | "\n", 48 | "To select a desired format from within JupyterLab, first activate the right sidebar by clicking on View in the Menu Toolbar.\n", 49 | "Then you ensure that in front of Show Right Sidebar there is a tick.\n", 50 | "Once the Right Sidebar is shown, you are ready to go.\n", 51 | "\n", 52 | "Now you select the cell containing your special code and choose options from the following dropdown menus:\n", 53 | "\n", 54 | "1. Select \"Raw\" in the Notebook Toolbar (just next to the symbols that run cells or reload the kernel).\n", 55 | "2. Click on \"Raw NBConvert Format\" in the Right Sidebar and select \"reStructured Text\".\n", 56 | "\n", 57 | "![Steps for converting cells to Raw formats in JupyterLab](images/raw_cells_jupyterlab.png)\n", 58 | "" 59 | ] 60 | }, 61 | { 62 | "cell_type": "markdown", 63 | "metadata": {}, 64 | "source": [ 65 | "## Available Raw Cell Formats\n", 66 | "\n", 67 | "The following examples show how different Jupyter cell formats are rendered by Sphinx." 68 | ] 69 | }, 70 | { 71 | "cell_type": "markdown", 72 | "metadata": {}, 73 | "source": [ 74 | "### None\n", 75 | "\n", 76 | "By default (if no cell format is selected), the cell content is included (without any conversion) in both the HTML and LaTeX output.\n", 77 | "This is typically not useful at all." 78 | ] 79 | }, 80 | { 81 | "cell_type": "raw", 82 | "metadata": {}, 83 | "source": [ 84 | "\"I'm a raw cell with no format.\"" 85 | ] 86 | }, 87 | { 88 | "cell_type": "markdown", 89 | "metadata": {}, 90 | "source": [ 91 | "### reST\n", 92 | "\n", 93 | "Raw cells in \"reST\" format are interpreted as reStructuredText and parsed by Sphinx.\n", 94 | "Thus, you can e.g. use its\n", 95 | "[cross-referencing abilities](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects)\n", 96 | "for automatically creating/updating links to the definition of modules, classes, functions, and similar.\n", 97 | "The result is visible in both HTML and LaTeX output." 98 | ] 99 | }, 100 | { 101 | "cell_type": "raw", 102 | "metadata": { 103 | "raw_mimetype": "text/restructuredtext" 104 | }, 105 | "source": [ 106 | "\"**I'm** a *raw cell* in reST_ format.\"\n", 107 | "\n", 108 | "I can contain Sphinx roles such as a link to :func:`example_python_function`.\n", 109 | "\n", 110 | ".. _reST: https://www.sphinx-doc.org/rest.html" 111 | ] 112 | }, 113 | { 114 | "cell_type": "markdown", 115 | "metadata": {}, 116 | "source": [ 117 | "### Markdown\n", 118 | "\n", 119 | "Raw cells in \"Markdown\" format are interpreted as Markdown, and the result is included in both HTML and LaTeX output. Since the Jupyter Notebook also supports normal Markdown cells, this might not be useful *at all*." 120 | ] 121 | }, 122 | { 123 | "cell_type": "raw", 124 | "metadata": { 125 | "raw_mimetype": "text/markdown" 126 | }, 127 | "source": [ 128 | "\"**I'm** a *raw cell* in [Markdown](https://daringfireball.net/projects/markdown/) format.\"" 129 | ] 130 | }, 131 | { 132 | "cell_type": "markdown", 133 | "metadata": {}, 134 | "source": [ 135 | "### HTML\n", 136 | "\n", 137 | "Raw cells in \"HTML\" format are only visible in HTML output. This option might not be very useful, since raw HTML code is also allowed within normal Markdown cells." 138 | ] 139 | }, 140 | { 141 | "cell_type": "raw", 142 | "metadata": { 143 | "raw_mimetype": "text/html" 144 | }, 145 | "source": [ 146 | "

“I’m a raw cell in\n", 147 | "HTML format.”

" 148 | ] 149 | }, 150 | { 151 | "cell_type": "markdown", 152 | "metadata": {}, 153 | "source": [ 154 | "### LaTeX\n", 155 | "\n", 156 | "Raw cells in \"LaTeX\" format are only visible in LaTeX output." 157 | ] 158 | }, 159 | { 160 | "cell_type": "raw", 161 | "metadata": { 162 | "raw_mimetype": "text/latex" 163 | }, 164 | "source": [ 165 | "\\textbf{I'm} a \\emph{raw cell} in \\href{https://www.latex-project.org/}{\\LaTeX} format." 166 | ] 167 | }, 168 | { 169 | "cell_type": "markdown", 170 | "metadata": {}, 171 | "source": [ 172 | "### Python\n", 173 | "\n", 174 | "Raw cells in \"Python\" format are not visible at all (nor executed in any way)." 175 | ] 176 | }, 177 | { 178 | "cell_type": "raw", 179 | "metadata": { 180 | "raw_mimetype": "text/x-python" 181 | }, 182 | "source": [ 183 | "print(\"I'm a raw cell in \\\"Python\\\" format!\")" 184 | ] 185 | } 186 | ], 187 | "metadata": { 188 | "celltoolbar": "Raw Cell Format", 189 | "kernelspec": { 190 | "display_name": "Python 3 (ipykernel)", 191 | "language": "python", 192 | "name": "python3" 193 | }, 194 | "language_info": { 195 | "codemirror_mode": { 196 | "name": "ipython", 197 | "version": 3 198 | }, 199 | "file_extension": ".py", 200 | "mimetype": "text/x-python", 201 | "name": "python", 202 | "nbconvert_exporter": "python", 203 | "pygments_lexer": "ipython3", 204 | "version": "3.8.8" 205 | } 206 | }, 207 | "nbformat": 4, 208 | "nbformat_minor": 4 209 | } 210 | -------------------------------------------------------------------------------- /doc/references.bib: -------------------------------------------------------------------------------- 1 | @article{perez2011python, 2 | author = {Pérez, Fernando and Granger, Brian E. and Hunter, John D.}, 3 | title = {Python: An Ecosystem for Scientific Computing}, 4 | journal = {Computing in Science Engineering}, 5 | volume = 13, 6 | number = 2, 7 | pages = {13--21}, 8 | doi = {10.1109/MCSE.2010.119}, 9 | year = 2011, 10 | } 11 | 12 | @incollection{kluyver2016jupyter, 13 | author = {Kluyver, Thomas and Ragan-Kelley, Benjamin and Pérez, Fernando and Granger, Brian and Bussonnier, Matthias and Frederic, Jonathan and Kelley, Kyle and Hamrick, Jessica and Grout, Jason and Corlay, Sylvain and Ivanov, Paul and Avila, Damián and Abdalla, Safia and Willing, Carol and {Jupyter Development Team}}, 14 | title = {{Jupyter Notebooks}---a publishing format for reproducible computational workflows}, 15 | booktitle = {Positioning and Power in Academic Publishing: Players, Agents and Agendas}, 16 | pages = {87--90}, 17 | publisher = {IOS Press}, 18 | doi = {10.3233/978-1-61499-649-1-87}, 19 | editor = {Loizides, Fernando and Schmidt, Birgit}, 20 | year = 2016, 21 | } 22 | -------------------------------------------------------------------------------- /doc/references.rst: -------------------------------------------------------------------------------- 1 | References 2 | ========== 3 | 4 | By default, in the LaTeX/PDF output the list of references will not appear here, 5 | but instead at the end of the document. 6 | For a possible work-around (which is also used here) 7 | see https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/156. 8 | 9 | The list of references may look something like this: 10 | 11 | .. raw:: latex 12 | 13 | \begingroup 14 | \def\section#1#2{} 15 | \def\chapter#1#2{} 16 | \begin{thebibliography}{1234} 17 | 18 | .. bibliography:: 19 | :style: alpha 20 | 21 | .. raw:: latex 22 | 23 | \end{thebibliography} 24 | \endgroup 25 | 26 | .. warning:: 27 | 28 | With ``docutils`` versions 0.18 and 0.19, 29 | the HTML output after the bibliography is broken, 30 | see https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/309. 31 | This problem has been fixed in ``docutils`` version 0.20. 32 | -------------------------------------------------------------------------------- /doc/requirements.txt: -------------------------------------------------------------------------------- 1 | ipykernel 2 | numpy 3 | matplotlib 4 | ipympl 5 | pandas 6 | xarray 7 | # setuptools seems to be needed for pybtex, see 8 | # https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/345: 9 | setuptools 10 | sphinxcontrib-bibtex>=2.1 11 | sphinxcontrib-svg2pdfconverter 12 | ipywidgets 13 | jupytext 14 | sphinx-last-updated-by-git 15 | sphinx-codeautolink 16 | -------------------------------------------------------------------------------- /doc/subdir/a-notebook-in-a-subdir.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Notebooks in Sub-Directories\n", 17 | "\n", 18 | "You can organize your notebooks in subdirectories and `nbsphinx` will take care that relative links to other notebooks, images and other files still work.\n", 19 | "\n", 20 | "Let's see if links to local images work: ![Jupyter notebook icon](../images/notebook_icon.png)" 21 | ] 22 | }, 23 | { 24 | "cell_type": "code", 25 | "execution_count": null, 26 | "metadata": {}, 27 | "outputs": [], 28 | "source": [ 29 | "from IPython.display import Image\n", 30 | "Image(filename='../images/notebook_icon.png')" 31 | ] 32 | }, 33 | { 34 | "cell_type": "markdown", 35 | "metadata": {}, 36 | "source": [ 37 | "
\n", 38 | "\n", 39 | "Warning\n", 40 | "\n", 41 | "There may be problems with images in output cells if your source directory contains symbolic links, see [issue #49](https://github.com/spatialaudio/nbsphinx/issues/49).\n", 42 | "\n", 43 | "
\n", 44 | "\n", 45 | "A link to a notebook in the same sub-directory: [link](toctree.ipynb).\n", 46 | "\n", 47 | "A link to a notebook in the parent directory: [link](../markdown-cells.ipynb).\n", 48 | "\n", 49 | "A link to a local file: [link](../images/notebook_icon.png).\n", 50 | "\n", 51 | "A random equation:\n", 52 | "\\begin{equation}\n", 53 | "F_n = F_{n-1} + F_{n-2}\n", 54 | "\\tag{08.15}\n", 55 | "\\label{fibonacci-recurrence}\n", 56 | "\\end{equation}\n", 57 | "\n", 58 | "## A Sub-Section\n", 59 | "\n", 60 | "This is just for testing inter-notebook links,\n", 61 | "see [this section](../markdown-cells.ipynb#Links-to-Other-Notebooks).\n", 62 | "\n", 63 | "## That's a \"Strange\" Section\n", 64 | "\n", 65 | "This is for testing links to a section title containing quotes." 66 | ] 67 | } 68 | ], 69 | "metadata": { 70 | "kernelspec": { 71 | "display_name": "Python 3 (ipykernel)", 72 | "language": "python", 73 | "name": "python3" 74 | }, 75 | "language_info": { 76 | "codemirror_mode": { 77 | "name": "ipython", 78 | "version": 3 79 | }, 80 | "file_extension": ".py", 81 | "mimetype": "text/x-python", 82 | "name": "python", 83 | "nbconvert_exporter": "python", 84 | "pygments_lexer": "ipython3", 85 | "version": "3.11.2" 86 | } 87 | }, 88 | "nbformat": 4, 89 | "nbformat_minor": 4 90 | } 91 | -------------------------------------------------------------------------------- /doc/subdir/gallery.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Creating Thumbnail Galleries\n", 17 | "\n", 18 | "Inspired by [Sphinx-Gallery](https://sphinx-gallery.github.io/),\n", 19 | "you can create thumbnail galleries from a list of Jupyter notebooks\n", 20 | "(or other Sphinx source files).\n", 21 | "\n", 22 | "`nbsphinx` provides CSS styles for galleries,\n", 23 | "but like all styles you can tweak them\n", 24 | "with your own CSS files loaded via\n", 25 | "[html_css_files](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files).\n", 26 | "If you want to disable all the original styling,\n", 27 | "you can create a file named `nbsphinx-gallery.css` somewhere in your\n", 28 | "[html_static_path](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path),\n", 29 | "which will replace the original CSS file\n", 30 | "(adding it to `html_css_files` is not necessary in this case,\n", 31 | "because it is automatically added by `nbsphinx`).\n", 32 | "\n", 33 | "The following sections present\n", 34 | "two different ways of creating thumbnail galleries\n", 35 | "in Jupyter notebooks\n", 36 | "and show how thumbnail images can be selected.\n", 37 | "Thumbnail galleries can also be created in\n", 38 | "[reStructuredText files](../a-normal-rst-file.rst#thumbnail-galleries)." 39 | ] 40 | }, 41 | { 42 | "cell_type": "markdown", 43 | "metadata": { 44 | "tags": [ 45 | "nbsphinx-toctree" 46 | ] 47 | }, 48 | "source": [ 49 | "* [Gallery With Nested Documents](../gallery/gallery-with-nested-documents.ipynb)\n", 50 | "* [Gallery With Links (HTML only)](../gallery/gallery-with-links.ipynb)" 51 | ] 52 | } 53 | ], 54 | "metadata": { 55 | "kernelspec": { 56 | "display_name": "Python 3 (ipykernel)", 57 | "language": "python", 58 | "name": "python3" 59 | }, 60 | "language_info": { 61 | "codemirror_mode": { 62 | "name": "ipython", 63 | "version": 3 64 | }, 65 | "file_extension": ".py", 66 | "mimetype": "text/x-python", 67 | "name": "python", 68 | "nbconvert_exporter": "python", 69 | "pygments_lexer": "ipython3", 70 | "version": "3.11.1" 71 | } 72 | }, 73 | "nbformat": 4, 74 | "nbformat_minor": 4 75 | } 76 | -------------------------------------------------------------------------------- /doc/subdir/toctree.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Using `toctree` In A Notebook\n", 17 | "\n", 18 | "In Sphinx-based documentation, there is typically a file called `index.rst` which contains one or more [toctree](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree) directives.\n", 19 | "Those can be used to pull in further source files (which themselves can contain further `toctree` directives).\n", 20 | "\n", 21 | "With `nbsphinx` it is possible to get a similar effect within a Jupyter notebook using the\n", 22 | "`nbsphinx-toctree` cell tag or cell metadata.\n", 23 | "Markdown cells with `nbsphinx-toctree` tag/metadata are not converted like \"normal\" Markdown cells.\n", 24 | "Instead, they are only scanned for links to other notebooks (or `*.rst` files and other Sphinx source files) and those links are added to a `toctree` directive.\n", 25 | "External links can also be used, but they will not be visible in the LaTeX output.\n", 26 | "\n", 27 | "If there is a section title in the selected cell,\n", 28 | "it is used as `toctree` caption (but it also works without a title).\n", 29 | "\n", 30 | "
\n", 31 | "\n", 32 | "Note\n", 33 | "\n", 34 | "All other content of such a cell is *ignored*!\n", 35 | "\n", 36 | "
\n", 37 | "\n", 38 | "If you are satisfied with the default settings,\n", 39 | "you can simply use `nbsphinx-toctree` as a cell tag.\n", 40 | "\n", 41 | "Alternatively, you can store `nbsphinx-toctree` cell metadata.\n", 42 | "Use ...\n", 43 | "\n", 44 | "```json\n", 45 | "{\n", 46 | " \"nbsphinx-toctree\": {}\n", 47 | "}\n", 48 | "```\n", 49 | "\n", 50 | "... for the default settings, ...\n", 51 | "\n", 52 | "```json\n", 53 | "{\n", 54 | " \"nbsphinx-toctree\": {\n", 55 | " \"maxdepth\": 2\n", 56 | " }\n", 57 | "}\n", 58 | "```\n", 59 | "\n", 60 | "... for setting the `:maxdepth:` option, or...\n", 61 | "\n", 62 | "```json\n", 63 | "{\n", 64 | " \"nbsphinx-toctree\": {\n", 65 | " \"hidden\": true\n", 66 | " }\n", 67 | "}\n", 68 | "```\n", 69 | "\n", 70 | "... for setting the `:hidden:` option.\n", 71 | "\n", 72 | "Of course, multiple options can be used at the same time, e.g.\n", 73 | "\n", 74 | "```json\n", 75 | "{\n", 76 | " \"nbsphinx-toctree\": {\n", 77 | " \"maxdepth\": 3,\n", 78 | " \"numbered\": true\n", 79 | " }\n", 80 | "}\n", 81 | "```\n", 82 | "\n", 83 | "For more options, have a look a the [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree).\n", 84 | "All options can be used -- except `:glob:`, which can only be used in [rst files](../a-normal-rst-file.rst) and in [raw reST cells](../raw-cells.ipynb#reST).\n", 85 | "\n", 86 | "
\n", 87 | "\n", 88 | "Note\n", 89 | "\n", 90 | "In HTML output, a `toctree` cell generates an in-line table of contents (containing links) at its position in the notebook, whereas in the LaTeX output, a new (sub-)section with the actual content is inserted at its position.\n", 91 | "All content below the `toctree` cell will appear after the table of contents/inserted section, respectively.\n", 92 | "If you want to use the LaTeX output, it is recommended that you don't add further cells below a `toctree` cell, otherwise their content may appear at unexpected places.\n", 93 | "Multiple `toctree` cells in a row should be fine, though.\n", 94 | "\n", 95 | "
\n", 96 | "\n", 97 | "The following cell is tagged with `nbsphinx-toctree` and contains a link to the notebook [yet-another.ipynb](../yet-another.ipynb) and an external link (which will only be visible in the HTML output).\n", 98 | "It also contains a section title which will be used as `toctree` caption\n", 99 | "(which also will only be visible in the HTML output)." 100 | ] 101 | }, 102 | { 103 | "cell_type": "markdown", 104 | "metadata": { 105 | "tags": [ 106 | "nbsphinx-toctree" 107 | ] 108 | }, 109 | "source": [ 110 | "The following section title will be converted to the `toctree` caption.\n", 111 | "\n", 112 | "## A sub-toctree\n", 113 | "\n", 114 | "[A Notebook that's just a \"toctree\" Target](../yet-another.ipynb)\n", 115 | "\n", 116 | "[An External Link (HTML only)](https://nbsphinx.readthedocs.io/)\n", 117 | "\n", 118 | "Only the first section title (optional) and links to other source files (and external links) are used,\n", 119 | "all other cell content (like this very sentence) is ignored!" 120 | ] 121 | } 122 | ], 123 | "metadata": { 124 | "kernelspec": { 125 | "display_name": "Python 3 (ipykernel)", 126 | "language": "python", 127 | "name": "python3" 128 | }, 129 | "language_info": { 130 | "codemirror_mode": { 131 | "name": "ipython", 132 | "version": 3 133 | }, 134 | "file_extension": ".py", 135 | "mimetype": "text/x-python", 136 | "name": "python", 137 | "nbconvert_exporter": "python", 138 | "pygments_lexer": "ipython3", 139 | "version": "3.11.1" 140 | } 141 | }, 142 | "nbformat": 4, 143 | "nbformat_minor": 4 144 | } 145 | -------------------------------------------------------------------------------- /doc/timeout.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Cell Execution Timeout\n", 17 | "\n", 18 | "By default, code cells will be executed until they are finished,\n", 19 | "even if that takes a very long time.\n", 20 | "In some cases they might never finish.\n", 21 | "\n", 22 | "If you would like to only use a finite amount of time per cell,\n", 23 | "you can choose a timeout length for all notebooks by setting the following option in [conf.py](conf.py):\n", 24 | "\n", 25 | "```python\n", 26 | "nbsphinx_timeout = 60\n", 27 | "```\n", 28 | "\n", 29 | "Or change the timeout length on a per-notebook basis by adding this to the notebook's JSON metadata:\n", 30 | "\n", 31 | "```\n", 32 | "\"nbsphinx\": {\n", 33 | " \"timeout\": 60\n", 34 | "},\n", 35 | "```\n", 36 | "\n", 37 | "The timeout is given in seconds, use `-1` to disable the timeout (which is the default).\n", 38 | "\n", 39 | "Alternatively, you can manually execute the notebook in question and save the results, see [the pre-executed example notebook](pre-executed.ipynb)." 40 | ] 41 | } 42 | ], 43 | "metadata": { 44 | "kernelspec": { 45 | "display_name": "Python 3", 46 | "language": "python", 47 | "name": "python3" 48 | }, 49 | "language_info": { 50 | "codemirror_mode": { 51 | "name": "ipython", 52 | "version": 3 53 | }, 54 | "file_extension": ".py", 55 | "mimetype": "text/x-python", 56 | "name": "python", 57 | "nbconvert_exporter": "python", 58 | "pygments_lexer": "ipython3", 59 | "version": "3.7.6" 60 | }, 61 | "nbsphinx": { 62 | "timeout": 60 63 | } 64 | }, 65 | "nbformat": 4, 66 | "nbformat_minor": 4 67 | } 68 | -------------------------------------------------------------------------------- /doc/version-history.rst: -------------------------------------------------------------------------------- 1 | Version History 2 | =============== 3 | 4 | .. include:: ../NEWS.rst 5 | -------------------------------------------------------------------------------- /doc/yet-another.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": { 6 | "nbsphinx": "hidden" 7 | }, 8 | "source": [ 9 | "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/." 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# Yet Another Notebook\n", 17 | "\n", 18 | "This notebook is only here to show how (sub-)toctrees can be created with Markdown cell metadata.\n", 19 | "See [there](subdir/toctree.ipynb)." 20 | ] 21 | } 22 | ], 23 | "metadata": { 24 | "kernelspec": { 25 | "display_name": "Python 3", 26 | "language": "python", 27 | "name": "python3" 28 | }, 29 | "language_info": { 30 | "codemirror_mode": { 31 | "name": "ipython", 32 | "version": 3 33 | }, 34 | "file_extension": ".py", 35 | "mimetype": "text/x-python", 36 | "name": "python", 37 | "nbconvert_exporter": "python", 38 | "pygments_lexer": "ipython3", 39 | "version": "3.5.1+" 40 | } 41 | }, 42 | "nbformat": 4, 43 | "nbformat_minor": 1 44 | } 45 | -------------------------------------------------------------------------------- /git_rebase_theme_branches.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | set -e 4 | 5 | fmt=' 6 | git checkout %(refname) 7 | git rebase master 8 | git push origin HEAD:%(refname:strip=3) --force 9 | echo "giving RTD some time to build the docs" 10 | sleep 10m 11 | ' 12 | 13 | eval "$(git for-each-ref --shell --format="$fmt" refs/remotes/origin/*-theme)" 14 | 15 | git checkout master 16 | -------------------------------------------------------------------------------- /include-in-latex/README.md: -------------------------------------------------------------------------------- 1 | Including Sphinx-Generated Content in a LaTeX Document 2 | ====================================================== 3 | 4 | This sub-directory is an example for how a Sphinx-based project 5 | (in this case the `nbsphinx` documentation) 6 | can be included as part or chapter of a larger, 7 | otherwise hand-written LaTeX document 8 | (in this case [my-latex-document.tex][]). 9 | 10 | This technique is not specific to `nbsphinx`, except for this one line: 11 | 12 | \usepackage{nbsphinx} 13 | 14 | If you want to use it without `nbsphinx`, just remove this line. 15 | 16 | The main idea of this setup is that Sphinx is called with 17 | the original source directory `../doc` 18 | but specifying this directory 19 | (which contains another [conf.py][] overriding some of the original settings) 20 | as configuration directory (with `-c .`): 21 | 22 | python -m sphinx ../doc _build -c . -b latex 23 | 24 | Note that even though Sphinx suggests that in its console messages, 25 | running LaTeX in the `_build` directory will *not* work, 26 | because the `.tex` file in there is not a stand-alone LaTeX document 27 | (it is based on a [minimalistic template][]). 28 | It is meant to be included in the file [my-latex-document.tex][] 29 | in this directory, so LaTeX has to be called from here: 30 | 31 | latexmk -pv 32 | 33 | The configuration file [latexmkrc][] manipulates the environment variable 34 | `TEXINPUTS` so that LaTeX can find all necessary files. 35 | 36 | [my-latex-document.tex]: my-latex-document.tex 37 | [conf.py]: conf.py 38 | [minimalistic template]: _templates/latex.tex_t 39 | [latexmkrc]: latexmkrc 40 | -------------------------------------------------------------------------------- /include-in-latex/_templates/latex.tex_t: -------------------------------------------------------------------------------- 1 | %% Generated by Sphinx. 2 | %% This is meant to be included in another LaTeX document. 3 | <%= body %> 4 | <%= atendofbody %> 5 | -------------------------------------------------------------------------------- /include-in-latex/conf.py: -------------------------------------------------------------------------------- 1 | from pathlib import Path 2 | 3 | import docutils 4 | import sphinx 5 | 6 | original_conf_py = Path(__file__).resolve().parent.parent / 'doc' / 'conf.py' 7 | locals().update(sphinx.config.eval_config_file(str(original_conf_py), tags)) 8 | 9 | templates_path = ['_templates'] 10 | html_favicon = None 11 | 12 | exclude_patterns = ['_build'] 13 | 14 | latex_documents = [( 15 | 'index', # main source file 16 | 'nbsphinx-chapter.tex', # output file 17 | '', # unused 18 | '', # unused 19 | 'howto', # use 'manual' to generate \chapter{}s instead of \section{}s 20 | True, # toctree_only. Use True to hide contents of main source file 21 | )] 22 | 23 | latex_engine = 'lualatex' 24 | 25 | # Additional configuration options can be added here. 26 | 27 | ############################################################################### 28 | # The rest of this file is for handling the bibliography: 29 | 30 | extensions.remove('sphinxcontrib.bibtex') 31 | exclude_patterns.append('references.rst') 32 | suppress_warnings = ['toc.excluded'] 33 | 34 | 35 | def cite_role(macroname): 36 | 37 | def role(name, rawtext, text, lineno, inliner, options=None, content=None): 38 | latex_code = rf'\{macroname}{{{text}}}' 39 | return [docutils.nodes.raw('', latex_code, format='latex')], [] 40 | 41 | return role 42 | 43 | 44 | def setup(app): 45 | app.add_role('cite', cite_role('parencite')) 46 | app.add_role('cite:t', cite_role('textcite')) 47 | -------------------------------------------------------------------------------- /include-in-latex/latexmkrc: -------------------------------------------------------------------------------- 1 | # Configuration for latexmk 2 | 3 | @default_files = ('my-latex-document'); 4 | 5 | #$pdf_mode = 1; # $pdflatex 6 | #$pdf_mode = 3; # $dvipdf 7 | $pdf_mode = 4; # $lualatex 8 | #$pdf_mode = 5; # $xelatex 9 | 10 | # Add current directory (and subdirs) to LaTeX path: 11 | ensure_path('TEXINPUTS', './/'); 12 | 13 | # syntax highlighting of code blocks: 14 | system("./pygmentize.py"); 15 | 16 | $clean_ext = "run.xml"; 17 | 18 | $bibtex_use = 2; # run always, delete .bbl files on cleanup 19 | -------------------------------------------------------------------------------- /include-in-latex/my-latex-document.tex: -------------------------------------------------------------------------------- 1 | \RequirePackage{luatex85} 2 | \documentclass[a4paper]{book} 3 | 4 | \newdimen\sphinxpxdimen 5 | \sphinxpxdimen=.75bp 6 | \ifdefined\pdfimageresolution \pdfimageresolution= 96\relax\fi 7 | 8 | \catcode`^^^^00a0\active\protected\def^^^^00a0{\leavevmode\nobreak\ } 9 | 10 | \usepackage{fontspec} 11 | \usepackage{mathpazo} 12 | \linespread{1.05} % see http://www.tug.dk/FontCatalogue/urwpalladio/ 13 | \setmainfont{TeX Gyre Pagella}[Numbers=OldStyle] 14 | \setmonofont{Latin Modern Mono Light}[Numbers=Lining] 15 | 16 | \usepackage{amsmath,amssymb,amstext} 17 | 18 | \usepackage{polyglossia} 19 | \setmainlanguage{english} 20 | 21 | \usepackage[booktabs]{sphinx} 22 | \sphinxsetup{ 23 | %verbatimwrapslines=false, 24 | %verbatimhintsturnover=false, 25 | div.note_border-TeXcolor={HTML}{E0E0E0}, 26 | div.note_border-width=0.5pt, 27 | div.warning_border-TeXcolor={HTML}{E0E0E0}, 28 | div.warning_border-width=1.5pt, 29 | div.warning_background-TeXcolor={HTML}{FBFBFB}, 30 | } 31 | \fvset{fontsize=\small} 32 | 33 | \usepackage{nbsphinx} 34 | 35 | \usepackage[ 36 | style=authoryear-comp, 37 | backref=true, 38 | ]{biblatex} 39 | % We need the original bibliography from the Sphinx project ... 40 | \addbibresource{../doc/references.bib} 41 | % ... and we can add our own if we want: 42 | \addbibresource{my-own-references.bib} 43 | 44 | % This should be the last package in the preamble: 45 | \usepackage{hyperref} 46 | 47 | \sphinxsetup{ 48 | InnerLinkColor={named}{black}, 49 | OuterLinkColor={named}{black}, 50 | } 51 | 52 | \title{Including Sphinx-Generated Content in a \LaTeX\ Document} 53 | 54 | \begin{document} 55 | 56 | \maketitle 57 | 58 | \tableofcontents 59 | 60 | \chapter{A Hand-Written \LaTeX\ Chapter} 61 | 62 | \section{References to Sphinx Content} 63 | 64 | We can create references to the Sphinx content, 65 | for example to section~\ref{code-cells:Code,-Output,-Streams}. 66 | 67 | 68 | \section{Bibliography} 69 | 70 | We can cite bibliography items from the Sphinx project: 71 | \parencite{perez2011python}. 72 | But we can also use our own bibliography file: 73 | \parencite{knuth1986texbook}. 74 | 75 | We only have to make sure that the bibliography keys are unique. 76 | 77 | \section{Code Blocks} 78 | 79 | We can use the \texttt{sphinxVerbatim} environment 80 | to get code blocks like those generated by Sphinx: 81 | 82 | \begin{sphinxVerbatim} 83 | some code 84 | \end{sphinxVerbatim} 85 | 86 | \begin{sphinxVerbatim}[commandchars=\\\{\}] 87 | some code with \emph{markup} 88 | \end{sphinxVerbatim} 89 | 90 | With a little additional work 91 | we can even use the same syntax highlighting as Sphinx uses: 92 | 93 | See \texttt{pygmentize.py}: 94 | 95 | \input{pygmentize.py} 96 | 97 | \dots and \texttt{latexmkrc}: 98 | 99 | \input{latexmkrc} 100 | 101 | \chapter{A Chapter Containing a Sphinx Project} 102 | 103 | Depending on whether the last element of \texttt{latex\_documents} 104 | (\url{https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-latex_documents}) 105 | is \texttt{False} or \texttt{True}, 106 | the content of the main source file (without the main heading) 107 | is shown here or not, respectively: 108 | 109 | % NB: The name of the input file is defined with latex_documents in conf.py: 110 | \input{_build/nbsphinx-chapter} 111 | 112 | \printbibliography[title=References,heading=bibintoc] 113 | 114 | \end{document} 115 | -------------------------------------------------------------------------------- /include-in-latex/my-own-references.bib: -------------------------------------------------------------------------------- 1 | @book{knuth1986texbook, 2 | author = {Donald E. Knuth}, 3 | title = {The \TeX{}book}, 4 | publisher = {Addison-Wesley}, 5 | year = {1986}, 6 | isbn = {0-201-13447-0}, 7 | } 8 | -------------------------------------------------------------------------------- /include-in-latex/pygmentize.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | from pathlib import Path 3 | 4 | from sphinx import highlighting 5 | 6 | 7 | def pygmentize(source, destination, lang=None): 8 | source = Path(source) 9 | destination = Path(destination) 10 | if lang is None: 11 | lang = source.suffix[1:] 12 | code = source.read_text() 13 | highlighter = highlighting.PygmentsBridge( 14 | 'latex', latex_engine='lualatex') 15 | hlcode = highlighter.highlight_block(code, lang) 16 | hlcode = hlcode.replace(r'\begin{Verbatim}', r'\begin{sphinxVerbatim}') 17 | hlcode = hlcode.replace(r'\end{Verbatim}', r'\end{sphinxVerbatim}') 18 | destination.parent.mkdir(exist_ok=True) 19 | destination.write_text(hlcode) 20 | 21 | 22 | if __name__ == '__main__': 23 | pygmentize('pygmentize.py', 'pygmentize.py.tex') 24 | pygmentize('latexmkrc', 'latexmkrc.tex', lang='perl') 25 | -------------------------------------------------------------------------------- /include-in-latex/sphinxlatexindbibtoc.sty: -------------------------------------------------------------------------------- 1 | % Empty file to disable the one provided by Sphinx 2 | -------------------------------------------------------------------------------- /include-in-latex/sphinxlatexstyleheadings.sty: -------------------------------------------------------------------------------- 1 | % This file disables the one provided by Sphinx 2 | \newcommand{\py@HeaderFamily}{} 3 | -------------------------------------------------------------------------------- /include-in-latex/sphinxoptionsgeometry.sty: -------------------------------------------------------------------------------- 1 | % Empty file to disable the one provided by Sphinx 2 | -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [build-system] 2 | requires = ["setuptools >= 40.8.0"] 3 | build-backend = "setuptools.build_meta" 4 | -------------------------------------------------------------------------------- /setup.py: -------------------------------------------------------------------------------- 1 | from pathlib import Path 2 | 3 | from setuptools import setup 4 | 5 | # "import" __version__ 6 | __version__ = 'unknown' 7 | with Path('src/nbsphinx/__init__.py').open() as f: 8 | for line in f: 9 | if line.startswith('__version__'): 10 | exec(line) 11 | break 12 | 13 | setup( 14 | name='nbsphinx', 15 | version=__version__, 16 | package_dir={'': 'src'}, 17 | packages=['nbsphinx'], 18 | package_data={'nbsphinx': [ 19 | '_static/nbsphinx-code-cells.css_t', 20 | '_static/nbsphinx-gallery.css', 21 | '_static/nbsphinx-no-thumbnail.svg', 22 | '_static/nbsphinx-broken-thumbnail.svg', 23 | '_texinputs/nbsphinx.sty', 24 | ]}, 25 | python_requires='>=3.6', 26 | install_requires=[ 27 | 'docutils>=0.18.1', 28 | 'jinja2', 29 | 'nbconvert>=5.3,!=5.4', 30 | 'traitlets>=5', 31 | 'nbformat', 32 | 'sphinx >= 1.8, != 8.2.0, != 8.2.1', 33 | ], 34 | author='Matthias Geier', 35 | author_email='Matthias.Geier@gmail.com', 36 | description='Jupyter Notebook Tools for Sphinx', 37 | long_description=Path('README.rst').read_text(), 38 | license='MIT', 39 | keywords='Sphinx Jupyter notebook'.split(), 40 | url='https://nbsphinx.readthedocs.io/', 41 | project_urls={ 42 | 'Documentation': 'https://nbsphinx.readthedocs.io/', 43 | 'Source Code': 'https://github.com/spatialaudio/nbsphinx/', 44 | 'Bug Tracker': 'https://github.com/spatialaudio/nbsphinx/issues/', 45 | }, 46 | platforms='any', 47 | classifiers=[ 48 | 'Framework :: Sphinx', 49 | 'Framework :: Sphinx :: Extension', 50 | 'Framework :: Jupyter', 51 | 'Intended Audience :: Education', 52 | 'Intended Audience :: Science/Research', 53 | 'Operating System :: OS Independent', 54 | 'Programming Language :: Python', 55 | 'Programming Language :: Python :: 3', 56 | 'Topic :: Documentation :: Sphinx', 57 | ], 58 | ) 59 | -------------------------------------------------------------------------------- /src/nbsphinx/_static/nbsphinx-broken-thumbnail.svg: -------------------------------------------------------------------------------- 1 | 2 | 8 | 9 | 10 | -------------------------------------------------------------------------------- /src/nbsphinx/_static/nbsphinx-code-cells.css_t: -------------------------------------------------------------------------------- 1 | /* remove conflicting styling from Sphinx themes */ 2 | div.nbinput.container div.prompt *, 3 | div.nboutput.container div.prompt *, 4 | div.nbinput.container div.input_area pre, 5 | div.nboutput.container div.output_area pre, 6 | div.nbinput.container div.input_area .highlight, 7 | div.nboutput.container div.output_area .highlight { 8 | border: none; 9 | padding: 0; 10 | margin: 0; 11 | box-shadow: none; 12 | } 13 | 14 | div.nbinput.container > div[class*=highlight], 15 | div.nboutput.container > div[class*=highlight] { 16 | margin: 0; 17 | } 18 | 19 | div.nbinput.container div.prompt *, 20 | div.nboutput.container div.prompt * { 21 | background: none; 22 | } 23 | 24 | div.nboutput.container div.output_area .highlight, 25 | div.nboutput.container div.output_area pre { 26 | background: unset; 27 | } 28 | 29 | div.nboutput.container div.output_area div.highlight { 30 | color: unset; /* override Pygments text color */ 31 | } 32 | 33 | /* avoid gaps between output lines */ 34 | div.nboutput.container div[class*=highlight] pre { 35 | line-height: normal; 36 | } 37 | 38 | /* input/output containers */ 39 | div.nbinput.container, 40 | div.nboutput.container { 41 | display: -webkit-flex; 42 | display: flex; 43 | align-items: flex-start; 44 | margin: 0; 45 | width: 100%; 46 | } 47 | @media (max-width: {{ nbsphinx_responsive_width }}) { 48 | div.nbinput.container, 49 | div.nboutput.container { 50 | flex-direction: column; 51 | } 52 | } 53 | 54 | /* input container */ 55 | div.nbinput.container { 56 | padding-top: 5px; 57 | } 58 | 59 | /* last container */ 60 | div.nblast.container { 61 | padding-bottom: 5px; 62 | } 63 | 64 | /* input prompt */ 65 | div.nbinput.container div.prompt pre, 66 | /* for sphinx_immaterial theme: */ 67 | div.nbinput.container div.prompt pre > code { 68 | color: #307FC1; 69 | } 70 | 71 | /* output prompt */ 72 | div.nboutput.container div.prompt pre, 73 | /* for sphinx_immaterial theme: */ 74 | div.nboutput.container div.prompt pre > code { 75 | color: #BF5B3D; 76 | } 77 | 78 | /* all prompts */ 79 | div.nbinput.container div.prompt, 80 | div.nboutput.container div.prompt { 81 | width: {{ nbsphinx_prompt_width }}; 82 | padding-top: 5px; 83 | position: relative; 84 | user-select: none; 85 | } 86 | 87 | div.nbinput.container div.prompt > div, 88 | div.nboutput.container div.prompt > div { 89 | position: absolute; 90 | right: 0; 91 | margin-right: 0.3ex; 92 | } 93 | 94 | @media (max-width: {{ nbsphinx_responsive_width }}) { 95 | div.nbinput.container div.prompt, 96 | div.nboutput.container div.prompt { 97 | width: unset; 98 | text-align: left; 99 | padding: 0.4em; 100 | } 101 | div.nboutput.container div.prompt.empty { 102 | padding: 0; 103 | } 104 | 105 | div.nbinput.container div.prompt > div, 106 | div.nboutput.container div.prompt > div { 107 | position: unset; 108 | } 109 | } 110 | 111 | /* disable scrollbars and line breaks on prompts */ 112 | div.nbinput.container div.prompt pre, 113 | div.nboutput.container div.prompt pre { 114 | overflow: hidden; 115 | white-space: pre; 116 | } 117 | 118 | /* input/output area */ 119 | div.nbinput.container div.input_area, 120 | div.nboutput.container div.output_area { 121 | -webkit-flex: 1; 122 | flex: 1; 123 | overflow: auto; 124 | } 125 | @media (max-width: {{ nbsphinx_responsive_width }}) { 126 | div.nbinput.container div.input_area, 127 | div.nboutput.container div.output_area { 128 | width: 100%; 129 | } 130 | } 131 | 132 | /* input area */ 133 | div.nbinput.container div.input_area { 134 | border: 1px solid #e0e0e0; 135 | border-radius: 2px; 136 | /*background: #f5f5f5;*/ 137 | } 138 | 139 | /* override MathJax center alignment in output cells */ 140 | div.nboutput.container div[class*=MathJax] { 141 | text-align: left !important; 142 | } 143 | 144 | /* override sphinx.ext.imgmath center alignment in output cells */ 145 | div.nboutput.container div.math p { 146 | text-align: left; 147 | } 148 | 149 | /* standard error */ 150 | div.nboutput.container div.output_area.stderr { 151 | background: #fdd; 152 | } 153 | 154 | /* ANSI colors */ 155 | .ansi-black-fg { color: #3E424D; } 156 | .ansi-black-bg { background-color: #3E424D; } 157 | .ansi-black-intense-fg { color: #282C36; } 158 | .ansi-black-intense-bg { background-color: #282C36; } 159 | .ansi-red-fg { color: #E75C58; } 160 | .ansi-red-bg { background-color: #E75C58; } 161 | .ansi-red-intense-fg { color: #B22B31; } 162 | .ansi-red-intense-bg { background-color: #B22B31; } 163 | .ansi-green-fg { color: #00A250; } 164 | .ansi-green-bg { background-color: #00A250; } 165 | .ansi-green-intense-fg { color: #007427; } 166 | .ansi-green-intense-bg { background-color: #007427; } 167 | .ansi-yellow-fg { color: #DDB62B; } 168 | .ansi-yellow-bg { background-color: #DDB62B; } 169 | .ansi-yellow-intense-fg { color: #B27D12; } 170 | .ansi-yellow-intense-bg { background-color: #B27D12; } 171 | .ansi-blue-fg { color: #208FFB; } 172 | .ansi-blue-bg { background-color: #208FFB; } 173 | .ansi-blue-intense-fg { color: #0065CA; } 174 | .ansi-blue-intense-bg { background-color: #0065CA; } 175 | .ansi-magenta-fg { color: #D160C4; } 176 | .ansi-magenta-bg { background-color: #D160C4; } 177 | .ansi-magenta-intense-fg { color: #A03196; } 178 | .ansi-magenta-intense-bg { background-color: #A03196; } 179 | .ansi-cyan-fg { color: #60C6C8; } 180 | .ansi-cyan-bg { background-color: #60C6C8; } 181 | .ansi-cyan-intense-fg { color: #258F8F; } 182 | .ansi-cyan-intense-bg { background-color: #258F8F; } 183 | .ansi-white-fg { color: #C5C1B4; } 184 | .ansi-white-bg { background-color: #C5C1B4; } 185 | .ansi-white-intense-fg { color: #A1A6B2; } 186 | .ansi-white-intense-bg { background-color: #A1A6B2; } 187 | 188 | .ansi-default-inverse-fg { color: #FFFFFF; } 189 | .ansi-default-inverse-bg { background-color: #000000; } 190 | 191 | .ansi-bold { font-weight: bold; } 192 | .ansi-underline { text-decoration: underline; } 193 | 194 | 195 | div.nbinput.container div.input_area div[class*=highlight] > pre, 196 | div.nboutput.container div.output_area div[class*=highlight] > pre, 197 | div.nboutput.container div.output_area div[class*=highlight].math, 198 | div.nboutput.container div.output_area.rendered_html, 199 | div.nboutput.container div.output_area > div.output_javascript, 200 | div.nboutput.container div.output_area:not(.rendered_html) > img{ 201 | padding: 5px; 202 | margin: 0; 203 | } 204 | 205 | /* fix copybtn overflow problem in chromium (needed for 'sphinx_copybutton') */ 206 | div.nbinput.container div.input_area > div[class^='highlight'], 207 | div.nboutput.container div.output_area > div[class^='highlight']{ 208 | overflow-y: hidden; 209 | } 210 | 211 | /* hide copy button on prompts for 'sphinx_copybutton' extension ... */ 212 | .prompt .copybtn, 213 | /* ... and 'sphinx_immaterial' theme */ 214 | .prompt .md-clipboard.md-icon { 215 | display: none; 216 | } 217 | 218 | /* Some additional styling taken form the Jupyter notebook CSS */ 219 | .jp-RenderedHTMLCommon table, 220 | div.rendered_html table { 221 | border: none; 222 | border-collapse: collapse; 223 | border-spacing: 0; 224 | color: black; 225 | font-size: 12px; 226 | table-layout: fixed; 227 | } 228 | .jp-RenderedHTMLCommon thead, 229 | div.rendered_html thead { 230 | border-bottom: 1px solid black; 231 | vertical-align: bottom; 232 | } 233 | .jp-RenderedHTMLCommon tr, 234 | .jp-RenderedHTMLCommon th, 235 | .jp-RenderedHTMLCommon td, 236 | div.rendered_html tr, 237 | div.rendered_html th, 238 | div.rendered_html td { 239 | text-align: right; 240 | vertical-align: middle; 241 | padding: 0.5em 0.5em; 242 | line-height: normal; 243 | white-space: normal; 244 | max-width: none; 245 | border: none; 246 | } 247 | .jp-RenderedHTMLCommon th, 248 | div.rendered_html th { 249 | font-weight: bold; 250 | } 251 | .jp-RenderedHTMLCommon tbody tr:nth-child(odd), 252 | div.rendered_html tbody tr:nth-child(odd) { 253 | background: #f5f5f5; 254 | } 255 | .jp-RenderedHTMLCommon tbody tr:hover, 256 | div.rendered_html tbody tr:hover { 257 | background: rgba(66, 165, 245, 0.2); 258 | } 259 | 260 | {% if html_theme in ['sphinx_rtd_theme', 'julia', 'dask_sphinx_theme'] %} 261 | /* CSS overrides for sphinx_rtd_theme */ 262 | 263 | /* 24px margin */ 264 | .nbinput.nblast.container, 265 | .nboutput.nblast.container { 266 | margin-bottom: 19px; /* padding has already 5px */ 267 | } 268 | 269 | /* ... except between code cells! */ 270 | .nblast.container + .nbinput.container { 271 | margin-top: -19px; 272 | } 273 | {% endif %} 274 | 275 | {#- 276 | vim:ft=css 277 | #} 278 | -------------------------------------------------------------------------------- /src/nbsphinx/_static/nbsphinx-gallery.css: -------------------------------------------------------------------------------- 1 | .nbsphinx-gallery { 2 | display: grid; 3 | grid-template-columns: repeat(auto-fill, minmax(160px, 1fr)); 4 | gap: 5px; 5 | margin-top: 1em; 6 | margin-bottom: 1em; 7 | } 8 | 9 | .nbsphinx-gallery > a { 10 | padding: 5px; 11 | border: 1px dotted currentColor; 12 | border-radius: 2px; 13 | text-align: center; 14 | } 15 | 16 | .nbsphinx-gallery > a:hover { 17 | border-style: solid; 18 | } 19 | 20 | .nbsphinx-gallery img { 21 | max-width: 100%; 22 | max-height: 100%; 23 | } 24 | 25 | .nbsphinx-gallery > a > div:first-child { 26 | display: flex; 27 | align-items: start; 28 | justify-content: center; 29 | height: 120px; 30 | margin-bottom: 5px; 31 | } 32 | -------------------------------------------------------------------------------- /src/nbsphinx/_static/nbsphinx-no-thumbnail.svg: -------------------------------------------------------------------------------- 1 | 2 | 8 | 9 | 10 | -------------------------------------------------------------------------------- /src/nbsphinx/_texinputs/nbsphinx.sty: -------------------------------------------------------------------------------- 1 | \ProvidesPackage{nbsphinx}[2023/02/06 nbsphinx code cells and more] 2 | 3 | \RequirePackage{sphinx} 4 | 5 | % MEMO: the nbsphinxfancyoutput environment recycles some internal Sphinx 6 | % LaTeX macros, as testify the @ in their names. At 5.1.0 these macros 7 | % got modified so we now have two cases for the nbsphinxfancyoutput 8 | % definition: Sphinx >= 5.1.0 or Sphinx < 5.1.0 (and >= 1.7.0 at least). 9 | 10 | % MEMO: since Sphinx 2.0 the upstream \sphinxincludegraphics is similar and 11 | % slightly better than the \nbsphinxincludegraphics defined here. So for the 12 | % >= 5.1.0 branch of nbsphinxfancyoutput, the code does no replacement of 13 | % \sphinxincludegraphics by \nbsphinxincludegraphics anymore. 14 | 15 | % Jupyter Notebook code cell colors 16 | \definecolor{nbsphinxin}{HTML}{307FC1} 17 | \definecolor{nbsphinxout}{HTML}{BF5B3D} 18 | \definecolor{nbsphinx-code-bg}{HTML}{F5F5F5} 19 | \definecolor{nbsphinx-code-border}{HTML}{E0E0E0} 20 | \definecolor{nbsphinx-stderr}{HTML}{FFDDDD} 21 | % ANSI colors for output streams and traceback highlighting 22 | \definecolor{ansi-black}{HTML}{3E424D} 23 | \definecolor{ansi-black-intense}{HTML}{282C36} 24 | \definecolor{ansi-red}{HTML}{E75C58} 25 | \definecolor{ansi-red-intense}{HTML}{B22B31} 26 | \definecolor{ansi-green}{HTML}{00A250} 27 | \definecolor{ansi-green-intense}{HTML}{007427} 28 | \definecolor{ansi-yellow}{HTML}{DDB62B} 29 | \definecolor{ansi-yellow-intense}{HTML}{B27D12} 30 | \definecolor{ansi-blue}{HTML}{208FFB} 31 | \definecolor{ansi-blue-intense}{HTML}{0065CA} 32 | \definecolor{ansi-magenta}{HTML}{D160C4} 33 | \definecolor{ansi-magenta-intense}{HTML}{A03196} 34 | \definecolor{ansi-cyan}{HTML}{60C6C8} 35 | \definecolor{ansi-cyan-intense}{HTML}{258F8F} 36 | \definecolor{ansi-white}{HTML}{C5C1B4} 37 | \definecolor{ansi-white-intense}{HTML}{A1A6B2} 38 | \definecolor{ansi-default-inverse-fg}{HTML}{FFFFFF} 39 | \definecolor{ansi-default-inverse-bg}{HTML}{000000} 40 | 41 | % Defaults for all code blocks, including, but not limited to code cells: 42 | \sphinxsetup{VerbatimColor={named}{nbsphinx-code-bg}} 43 | \sphinxsetup{VerbatimBorderColor={named}{nbsphinx-code-border}} 44 | \@ifpackagelater{sphinx}{2022/06/30}{% Sphinx >= 5.1.0 45 | % Restore settings from Sphinx < 5.1.0: 46 | \sphinxsetup{pre_border-radius=0pt} 47 | \sphinxsetup{pre_box-decoration-break=clone} 48 | }{} 49 | 50 | % Define an environment for non-plain-text code cell outputs (e.g. images) 51 | \newbox\nbsphinxpromptbox 52 | \@ifpackagelater{sphinx}{2022/06/30}{% "later" means here "at least" 53 | % In this branch Sphinx is at least at 5.1.0 54 | \newenvironment{nbsphinxfancyoutput}{% 55 | \sphinxcolorlet{VerbatimColor}{white}% 56 | \spx@verb@boxes@fcolorbox@setup 57 | % for \sphinxincludegraphics check of maximal height 58 | \spx@image@maxheight \textheight 59 | \advance\spx@image@maxheight -\spx@boxes@border@top 60 | \advance\spx@image@maxheight -\spx@boxes@padding@top 61 | \advance\spx@image@maxheight -\spx@boxes@padding@bottom 62 | \advance\spx@image@maxheight -\spx@boxes@border@bottom 63 | \advance\spx@image@maxheight -\baselineskip 64 | \def\sphinxVerbatim@Before{\nbsphinxfancyaddprompt}% 65 | \def\sphinxVerbatim@After {\@empty}% 66 | \def\FrameCommand {\sphinxVerbatim@FrameCommand}% 67 | \def\FirstFrameCommand{\sphinxVerbatim@FirstFrameCommand}% 68 | \def\MidFrameCommand {\sphinxVerbatim@MidFrameCommand}% 69 | \def\LastFrameCommand {\sphinxVerbatim@LastFrameCommand}% 70 | \MakeFramed{\advance\hsize-\width\@totalleftmargin\z@\linewidth\hsize\@setminipage}% 71 | \lineskip=1ex\lineskiplimit=1ex\raggedright% 72 | }{\par\unskip\@minipagefalse\endMakeFramed} 73 | \def\nbsphinxfancyaddprompt{\ifvoid\nbsphinxpromptbox\else 74 | \kern\spx@boxes@border@top\kern\spx@boxes@padding@top 75 | \copy\nbsphinxpromptbox 76 | \kern-\ht\nbsphinxpromptbox\kern-\dp\nbsphinxpromptbox 77 | \kern-\spx@boxes@padding@top\kern-\spx@boxes@border@top 78 | \nointerlineskip 79 | \fi} 80 | }% End of Sphinx >= 5.1.0 branch 81 | {% This branch for Sphinx < 5.1.0 82 | \newenvironment{nbsphinxfancyoutput}{% 83 | % Avoid fatal error with framed.sty if graphics too long to fit on one page 84 | \let\sphinxincludegraphics\nbsphinxincludegraphics 85 | \nbsphinx@image@maxheight\textheight 86 | \advance\nbsphinx@image@maxheight -2\fboxsep % default \fboxsep 3pt 87 | \advance\nbsphinx@image@maxheight -2\fboxrule % default \fboxrule 0.4pt 88 | \advance\nbsphinx@image@maxheight -\baselineskip 89 | \def\nbsphinxfcolorbox{\spx@fcolorbox{nbsphinx-code-border}{white}}% 90 | \def\FrameCommand{\nbsphinxfcolorbox\nbsphinxfancyaddprompt\@empty}% 91 | \def\FirstFrameCommand{\nbsphinxfcolorbox\nbsphinxfancyaddprompt\sphinxVerbatim@Continues}% 92 | \def\MidFrameCommand{\nbsphinxfcolorbox\sphinxVerbatim@Continued\sphinxVerbatim@Continues}% 93 | \def\LastFrameCommand{\nbsphinxfcolorbox\sphinxVerbatim@Continued\@empty}% 94 | \MakeFramed{\advance\hsize-\width\@totalleftmargin\z@\linewidth\hsize\@setminipage}% 95 | \lineskip=1ex\lineskiplimit=1ex\raggedright% 96 | }{\par\unskip\@minipagefalse\endMakeFramed} 97 | \def\nbsphinxfancyaddprompt{\ifvoid\nbsphinxpromptbox\else 98 | \kern\fboxrule\kern\fboxsep 99 | \copy\nbsphinxpromptbox 100 | \kern-\ht\nbsphinxpromptbox\kern-\dp\nbsphinxpromptbox 101 | \kern-\fboxsep\kern-\fboxrule\nointerlineskip 102 | \fi} 103 | }% end of Sphinx < 5.1.0 branch 104 | \newlength\nbsphinxcodecellspacing 105 | \setlength{\nbsphinxcodecellspacing}{0pt} 106 | 107 | % Define support macros for attaching opening and closing lines to notebooks 108 | \newsavebox\nbsphinxbox 109 | \newcommand{\nbsphinxstartnotebook}[1]{% 110 | \par 111 | % measure needed space 112 | \setbox\nbsphinxbox\vtop{{#1\par}} 113 | % reserve some space at bottom of page, else start new page 114 | \needspace{\dimexpr2.5\baselineskip+\ht\nbsphinxbox+\dp\nbsphinxbox} 115 | % mimic vertical spacing from \section command 116 | \addpenalty\@secpenalty 117 | \@tempskipa 3.5ex \@plus 1ex \@minus .2ex\relax 118 | \addvspace\@tempskipa 119 | {\Large\@tempskipa\baselineskip 120 | \advance\@tempskipa-\prevdepth 121 | \advance\@tempskipa-\ht\nbsphinxbox 122 | \ifdim\@tempskipa>\z@ 123 | \vskip \@tempskipa 124 | \fi} 125 | \unvbox\nbsphinxbox 126 | % if notebook starts with a \section, prevent it from adding extra space 127 | \@nobreaktrue\everypar{\@nobreakfalse\everypar{}}% 128 | % compensate the parskip which will get inserted by next paragraph 129 | \nobreak\vskip-\parskip 130 | % do not break here 131 | \nobreak 132 | }% end of \nbsphinxstartnotebook 133 | 134 | \newcommand{\nbsphinxstopnotebook}[1]{% 135 | \par 136 | % measure needed space 137 | \setbox\nbsphinxbox\vbox{{#1\par}} 138 | \nobreak % it updates page totals 139 | \dimen@\pagegoal 140 | \advance\dimen@-\pagetotal \advance\dimen@-\pagedepth 141 | \advance\dimen@-\ht\nbsphinxbox \advance\dimen@-\dp\nbsphinxbox 142 | \ifdim\dimen@<\z@ 143 | % little space left 144 | \unvbox\nbsphinxbox 145 | \kern-.8\baselineskip 146 | \nobreak\vskip\z@\@plus1fil 147 | \penalty100 148 | \vskip\z@\@plus-1fil 149 | \kern.8\baselineskip 150 | \else 151 | \unvbox\nbsphinxbox 152 | \fi 153 | }% end of \nbsphinxstopnotebook 154 | 155 | % Ensure height of an included graphics fits in nbsphinxfancyoutput frame 156 | % The Sphinx >= 5.1.0 version of nbsphinxfancyoutput does not use this macro 157 | % as \sphinxincludegraphics is since Sphinx 2.0 similar and slightly better. 158 | \newdimen\nbsphinx@image@maxheight % set in nbsphinxfancyoutput environment 159 | \newcommand*{\nbsphinxincludegraphics}[2][]{% 160 | \gdef\spx@includegraphics@options{#1}% 161 | \setbox\spx@image@box\hbox{\includegraphics[#1,draft]{#2}}% 162 | \in@false 163 | \ifdim \wd\spx@image@box>\linewidth 164 | \g@addto@macro\spx@includegraphics@options{,width=\linewidth}% 165 | \in@true 166 | \fi 167 | % no rotation, no need to worry about depth 168 | \ifdim \ht\spx@image@box>\nbsphinx@image@maxheight 169 | \g@addto@macro\spx@includegraphics@options{,height=\nbsphinx@image@maxheight}% 170 | \in@true 171 | \fi 172 | \ifin@ 173 | \g@addto@macro\spx@includegraphics@options{,keepaspectratio}% 174 | \fi 175 | \setbox\spx@image@box\box\voidb@x % clear memory 176 | \expandafter\includegraphics\expandafter[\spx@includegraphics@options]{#2}% 177 | }% end of "\MakeFrame"-safe variant of \sphinxincludegraphics 178 | 179 | \renewcommand*\sphinx@verbatim@nolig@list{\do\'\do\`} 180 | \begingroup 181 | \catcode`'=\active 182 | \let\nbsphinx@noligs\@noligs 183 | \g@addto@macro\nbsphinx@noligs{\let'\PYGZsq} 184 | \endgroup 185 | \renewcommand*\sphinxbreaksbeforeactivelist{\do\<\do\"\do\'} 186 | \renewcommand*\sphinxbreaksafteractivelist{\do\.\do\,\do\:\do\;\do\?\do\!\do\/\do\>\do\-} 187 | \fvset{codes*=\sphinxbreaksattexescapedchars\do\^\^\let\@noligs\nbsphinx@noligs} 188 | 189 | \endinput 190 | -------------------------------------------------------------------------------- /theme_comparison.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | """Build multiple versions of the docs with different themes. 3 | 4 | If no THEME-NAMES are given, all theme branches will be built. 5 | 6 | All options after -- are passed to Sphinx. 7 | 8 | A requirements file can be created with the --requirements (or -r) flag. 9 | Those requirements can be installed with: 10 | 11 | python3 -m pip install -r theme_comparison/theme_requirements.txt 12 | 13 | """ 14 | import argparse 15 | from pathlib import Path 16 | 17 | from sphinx.cmd.build import build_main 18 | 19 | 20 | parser = argparse.ArgumentParser( 21 | description=__doc__, 22 | usage='%(prog)s [OPTIONS] [THEME-NAMES] [-- SPHINX-OPTIONS]', 23 | formatter_class=argparse.RawDescriptionHelpFormatter) 24 | parser.add_argument( 25 | '-l', '--list-themes', action='store_true', 26 | help='show list of available themes and exit') 27 | parser.add_argument( 28 | '-r', '--requirements', action='store_true', 29 | help='create theme_requirements.txt and exit') 30 | parser.add_argument( 31 | '-f', '--fetch', action='store_true', 32 | help='fetch latest data from "upstream"') 33 | parser.add_argument( 34 | 'themes', metavar='THEME-NAMES', nargs=argparse.REMAINDER, 35 | help='theme names (according to "*-theme" branch names)') 36 | args = parser.parse_args() 37 | 38 | try: 39 | import git 40 | except ImportError as e: 41 | parser.exit( 42 | 'The Python package GitPython has to be installed:\n\n' 43 | ' python3 -m pip install GitPython\n') 44 | 45 | main_dir = Path(__file__).resolve().parent / 'theme_comparison' 46 | main_dir.mkdir(exist_ok=True) 47 | repo = git.Repo(main_dir, search_parent_directories=True) 48 | for remote in repo.remotes: 49 | if any('spatialaudio/nbsphinx' in url for url in remote.urls): 50 | if args.fetch: 51 | remote.fetch() 52 | break 53 | else: 54 | if args.fetch: 55 | remote = repo.create_remote( 56 | 'upstream', 57 | 'https://github.com/spatialaudio/nbsphinx.git') 58 | remote.fetch() 59 | else: 60 | parser.error('no upstream remote found, use --fetch to download') 61 | 62 | available_themes = ( 63 | (ref.remote_head[:-len('-theme')], ref.name) 64 | for ref in remote.refs 65 | if ref.remote_head.endswith('-theme') 66 | ) 67 | 68 | if args.list_themes: 69 | for theme, _ in available_themes: 70 | print(theme) 71 | parser.exit(0) 72 | 73 | try: 74 | end_of_args = args.themes.index('--') 75 | except ValueError: 76 | end_of_args = len(args.themes) 77 | requested_themes = args.themes[:end_of_args] 78 | sphinx_options = args.themes[end_of_args + 1:] 79 | 80 | if requested_themes: 81 | selected_themes = [] 82 | for theme, branch in available_themes: 83 | if theme in requested_themes: 84 | selected_themes.append((theme, branch)) 85 | requested_themes.remove(theme) 86 | if requested_themes: 87 | parser.error(f'theme(s) not found: {requested_themes}') 88 | else: 89 | selected_themes = available_themes 90 | 91 | worktree_dir = main_dir / '_worktree' 92 | if not worktree_dir.exists(): 93 | repo.git.worktree('prune') 94 | repo.git.worktree('add', worktree_dir, '--detach') 95 | 96 | worktree = git.Git(worktree_dir) 97 | head_commit = repo.git.rev_parse('HEAD') 98 | worktree.reset(head_commit, '--hard') 99 | stash_commit = repo.git.stash('create', '--include-untracked') 100 | if stash_commit: 101 | worktree.merge(stash_commit) 102 | base_commit = worktree.rev_parse('HEAD') 103 | 104 | 105 | def run_with_all_themes(func): 106 | try: 107 | for name, branch in selected_themes: 108 | worktree.cherry_pick(branch) 109 | func(name, branch) 110 | worktree.reset(base_commit, '--hard') 111 | finally: 112 | worktree.reset(head_commit, '--hard') 113 | repo.git.worktree('prune') 114 | 115 | 116 | if args.requirements: 117 | requirements = set() 118 | 119 | def collect_requirements(name, branch): 120 | path = worktree_dir / 'doc' / 'requirements.txt' 121 | requirements.update(path.read_text().splitlines()) 122 | 123 | run_with_all_themes(collect_requirements) 124 | path = Path(repo.working_tree_dir) / 'doc' / 'requirements.txt' 125 | requirements.difference_update(path.read_text().splitlines()) 126 | path = main_dir / 'theme_requirements.txt' 127 | path.write_text('\n'.join(sorted(requirements))) 128 | print('Requirements written to', path) 129 | parser.exit(0) 130 | 131 | 132 | def build_docs(name, branch): 133 | print('#' * 80) 134 | print('#', name.upper().center(76), '#') 135 | print('#' * 80) 136 | result = build_main([ 137 | str(worktree_dir / 'doc'), 138 | str(main_dir / name), 139 | '-d', str(main_dir / '_cache'), 140 | '-Drelease=dummy', 141 | '-Dversion=dummy', 142 | '-Dtoday=dummy', 143 | '-Dhtml_title=nbsphinx-theme-comparison', 144 | *sphinx_options, 145 | ]) 146 | if result != 0: 147 | parser.exit(result) 148 | print('') 149 | 150 | 151 | run_with_all_themes(build_docs) 152 | --------------------------------------------------------------------------------