---
myst:
  substitutions:
    Folder: "{ref}`Folder<installation>`"

---

(examples_page)=
# Examples

 While the majority of the **kdFlex** software is written in
`C++`, Python bindings for the `C++` classes are available as Python
extensions. 
Example Python scripts, named `notebook.py`,  are available within each of the
subfolders within `/usr/share/Karana/Tutorials` in your local
installation (`/opt/homebrew/share/Karana/Tutorials` if using macOS). These scripts illustrate the use of the **kdFlex** Python extension and can be run from within each of these folders by
running `python3 notebook.py`. 

There are also `Jupyter notebook` versions of each of the tutorials, named `notebook.ipynb` within the same folder. The [introduction video](https://portal.karanadyn.com/tutorial_videos/intro_video.mp4) shows how to run these notebooks from a remote machine, from a local machine, and as a normal Python script.

(notebooks_page)=
## Python Tutorial Notebooks

This section contains tutorial examples on using **kdFlex**. The Python
examples are included here, since the associated Jupyter notebooks can be converted to HTML.



(installation)=
### Installation folder
The
notebooks tutorials are located under `/usr/share/Karana/Tutorials` (`/opt/homebrew/share/Karana/Tutorials` if using macOS).
The C++ examples cannot be easily converted to a web format, but are included with the kdflex package
as well under `/usr/share/Karana/Tutorials/example_cc` (or `/opt/homebrew/share/Karana/Tutorials/example_cc`) if 
using macOS.  One or more tags can be selected to filter down the list of notebooks.

Each notebook has a corresponding `notebook.py`, which is a regular `Python` script. 

### Listing

[Example listing](generated/notebook_listing)

<!--
NOTEBOOK METADATA GUIDELINES

This is how to get a notebook to show up in the listing

- Run jupyter notebook and open the corresponding notebook in your browser
- In the toolbar click Edit > Edit Notebook Metadata
- Add a top-level "docs" object to the Json. Within docs, a "tags" key is required and should map to a list of strings. Within docs, a "recording" key is optional and if given should map to the absolute URL of the video. Here's an example of what the Json metadata might look like:

    {
      "docs": {
        "recording": "https://portal.karanadyn.com/tutorial_videos/example_urdf.mp4",
        "tags": [
          "dynamics",
          "urdf",
          "import",
          "robot",
          "WAM"
        ]
      },
      "kernelspec": {
        "name": "python3",
        "display_name": "Python 3 (ipykernel)",
        "language": "python"
      },
      "language_info": {
        "name": "python",
        "version": "3.12.3",
        "mimetype": "text/x-python",
        "codemirror_mode": {
          "name": "ipython",
          "version": 3
        },
        "pygments_lexer": "ipython3",
        "nbconvert_exporter": "python",
        "file_extension": ".py"
      },
      "name": "notebook.ipynb"
    }

- The automated listing will use the header of the first markdown cell as the notebook title in the listing. For a given notebook this may differ from the old manual listing in this document. Determine what title should be used everywhere and make that be the header of the first markdown cell.
- Similarly, the automated listing will use the rest of the first markdown cell as the listing description, which likely differs from the description in the old manual listing in this document. Determine what description should be used everywhere and put it in the first markdown cell. Feel free to split up the first markdown cell of the notebook to put more exposition in the second cell and not have it be captured as the description. The description should not contain images or raw html.
- After making these changes and rebuilding the docs, the listing should show up in kd.internal/docs/generated/notebook_listing.html

-->