Sphinx extension: JupyterBook-Patches

This Sphinx extension fixes:

• with a layout patch:
  • an issue where drop down menus would still take up space after being minimized, and the patch fixes it through some css.
  • an issue where in drop down code cells the shown summary remained lightgray instead of turning darkgrey. Fix through css.
  • an issue where the size of code in a header is not the correct font size. Fix through css.
  • an issue where the sidebar shows a scrollbar even if that's not needed
  • an issue where the margin causes a scroll bar for a window between 992 and 1200px.
  • an issue where the caption text of a figure is aligned on the left for multi-line caption text.
  • an issue where code inside code-cells are aligned according to the parent element, instead of left-aligned.
• with a button patch:
  • an issue where two buttons for interactive matplotlib widget do not appear.
• with a mathjax patch:
  • an issue where in the Firefox browser the CHTML renderer of MathJax does not render thin lines consistently. Fixed by selecting the SVG renderer only for the Firefox browser.
  • an issue where rendered MathJax using the CHTML renderer is sometimes clipped at the top and/or the right. Fixed by adding some css to improve the appearance of MathJax elements.
  • that makes the default loading method of MathJax to be lazy loading, which improves page load times. Can be disabled if needed by either
    • disabling the mathjax patch (this also disables the Firefox fix); or
    • adding ui/nonlazy to config.mathjax3_config['loader']['load'] in your config file as shown below. This value is not defined by MathJax, but introduced by JupyterBook-Patches to allow disabling lazy loading.

      sphinx:
        config:
          mathjax3_config:
            loader:
              load:
                - "ui/nonlazy"
      

• with a download patch:
  • an issue where the standard download button for downloading .ipynb and .md files opens a new tab in some browsers instead of downloading the file. Fixed by adding the download attribute to the download links.
• with a hash patch:
  • an issue where if the URL contains a specific element id, the page scrolls to the element on the initial/partial page load and does not scroll to that element after complete page load. Fixed by adding a small javascript that scrolls to the element after complete page load.
• with a preserve_dropdown_state patch:
  • an issue where reloading a page causes all dropdown/collapsible admonitions to reset to their default state. Fixed by saving and restoring the open/closed state of all dropdowns using sessionStorage. Supports multiple dropdown types including:
    • details.dropdown - Standard HTML details dropdowns
    • details.sd-dropdown - Sphinx Design dropdowns
    • details.toggle-details - Toggle details elements
    • div.dropdown - Div-based admonition dropdowns with toggle buttons
• with a margin patch:
  • that allows the definition of margin/aside elements inside admonitions, instead of only outside. In other words:
  • a margin directive can now be nested within one other admonition.
  • a non-figure directive with the class margin can now be nested within one other admonition.
  • a figure directive with the figclass margin or margin-caption can now be nested within one other admonition.
  • Note that this not apply to code-cell directives, as those are not supported inside other directives.
• with a mystnb patch:
  • an issue where colon fences (such as :::) for top-level code-cells were not allowed.
    • Colon fences (such as :::) for top-level code-cells are now allowed, next to backtick fences (such as ```), inside markdown files.
  • an issue where the include directive did not correctly handle included content from markdown files with top-level code-cells and/or YAML front-matter from markdown files.
    • The include directive now correctly handles included content from markdown files with top-level code-cells and/or YAML front-matter from markdown files.
  • an issue where markdown files that contain and/or include top-level code-cells were not ensured to be a text-based notebook file.
    • Markdown files that contain and/or include top-level code-cells are ensured to be a text-based notebook file.
• with an index patch:
  • that adds a sticky jumpbox to the index page, allowing users to quickly navigate to different sections of the index.
  • that adds a scroll-margin-top to the index headings, ensuring that when users click on a jumpbox link, the corresponding section is not hidden behind the sticky jumpbox.
  • that sorts the multiple instances of the same index entry based on the order of the documents in the toctree, instead of sorting them alphabetically. This ensures that the index entries are displayed in a more logical and user-friendly manner.
  • displays index entries with multiple instances in a more logical manner. For example, if the entry "foo" appears four times, the index originally displayed it as:

    foo, [1], [2], [3]
    

    where foo, [1], [2] and [3] are links to the four instances of "foo". The patch now displays it as:

    foo [1], [2], [3], [4]
    

Installation

To install the Sphinx-JupyterBook-Patches, follow these steps:

Step 1: Install the Package

Install the jupyterbook_patches package using pip:

pip install jupyterbook_patches

Step 2: Add to requirements.txt

Make sure that the package is included in your project's requirements.txt to track the dependency:

jupyterbook_patches

Step 3: Enable in _config.yml

In your _config.yml file, add the extension to the list of Sphinx extra extensions:

sphinx: 
    extra_extensions:
        - jupyterbook_patches

Step 4 (optional): Disable patches in _config.yml

In your _config.yml file, add disable patches you do not wish:

sphinx: 
    config:
        patch_config:
            disabled-patches: []

Replace [] by a list of strings to disable patches. Use the patch name as indicated at the top of this document.

For example, to disable the mathjax patch:

sphinx: 
    config:
        patch_config:
            disabled-patches: ["mathjax"]

For example, to disable the layout and button patches:

sphinx: 
    config:
        patch_config:
            disabled-patches: ["button","layout"]

Part of TeachBooks Favourites

This extension is part of TeachBooks Favourites, a Sphinx extension which collects all of TeachBooks' favourite features in one place.

Contribute

This tool's repository is stored on GitHub. The README.md of the branch manual_docs is also part of the TeachBooks manual as a submodule. If you'd like to contribute, you can create a fork and open a pull request on the GitHub repository. To update the README.md shown in the TeachBooks manual, create a fork and open a merge request for the GitHub repository of the manual. If you intent to clone the manual including its submodules, clone using: git clone --recurse-submodulesgit@github.com:TeachBooks/manual.git.