Use nbsphinx

nbsphinx uses a source parser for Jupyter notebooks (IPYNB files) to generate interactive examples. This extension uses custom Sphinx directives to show notebook code cells (and their results) in both HTML and LaTeX output. If a notebook is unevaluated (has no stored output cells), it is automatically executed during the Sphinx documentation build process. Notebooks with stored output cells are not executed by default.

Install Jupyter kernel

To execute and convert Jupyter notebooks, you must have the appropriate Jupyter kernel installed in your development environment. For example, you can install the IPython kernel from the ipykernel package.

Create and document notebooks

When using nbsphinx, you place the IPYNB files for the “Examples” section in the examples directory. To add documentation to your notebooks, use Markdown cells.

Configure the use of nbsphinx in the Sphinx configuration file

To build the “Examples” section, developers configure the use of the nbsphinx extension in the project’s conf.py file. After installing and adding this extension to the extensions variable as described in Add Sphinx extensions, developers configure the nbsphinx_execute and nbsphinx_thumbnails variables.

Here is what these variables look like in the conf.py file for PyAnsys Geometry:

# Examples gallery customization
nbsphinx_execute = "always"
nbsphinx_custom_formats = {
    ".mystnb": ["jupytext.reads", {"fmt": "mystnb"}],
}
nbsphinx_thumbnails = {
    "examples/01_getting_started/01_math": "_static/thumbnails/101_getting_started.png",
    "examples/01_getting_started/02_units": "_static/thumbnails/101_getting_started.png",
    "examples/01_getting_started/03_sketching": "_static/thumbnails/101_getting_started.png",
    "examples/01_getting_started/04_modeling": "_static/thumbnails/101_getting_started.png",
     "examples/01_getting_started/05_plotter_picker": "_static/thumbnails/101_getting_started.png",  # noqa: E501
     "examples/02_sketching/basic_usage": "_static/thumbnails/basic_usage.png",
     "examples/02_sketching/dynamic_sketch_plane": "_static/thumbnails/dynamic_sketch_plane.png",
     "examples/02_sketching/advanced_sketching_gears": "_static/thumbnails/advanced_sketching_gears.png",  # noqa: E501
     "examples/03_modeling/add_design_material": "_static/thumbnails/add_design_material.png",
     "examples/03_modeling/plate_with_hole": "_static/thumbnails/plate_with_hole.png",
     "examples/03_modeling/tessellation_usage": "_static/thumbnails/tessellation_usage.png",
     "examples/03_modeling/design_organization": "_static/thumbnails/design_organization.png",
     "examples/03_modeling/boolean_operations": "_static/thumbnails/boolean_operations.png",
}
nbsphinx_epilog = """

Add nbsphinx to the documentation requirements

To include nbsphinx in your project’s documentation requirements, you must add it as a dependency. Depending on the project’s configuration, you add the required pip packages in either the pyproject.toml file or the requirements_doc_txt file. For more information, see Add the extension to the documentation requirements.