Jupyter Notebook Examples

PyCRAM uses Jupyter Notebooks as a means of providing code examples and tutorials. These examples are located in the examples directory.

These Notebooks are stored as Myst Markdown files, which provide the advantage of better verison control and easier integration with Sphinx documentation. However, the Notebooks can be run as usual in Jupyter Notebook.

Running Examples

Despite the examples being stored as Myst Markdown files, they can still be run as Jupyter Notebooks. To run an example, simply open the Notebook in Jupyter Notebook and run the cells as you would with any other Notebook.

To run Jupyter Notebook, you need to have Jupyter Notebook installed. You can install Jupyter Notebook using pip:

pip install jupyter

After installing Jupyter Notebook, you can run it by executing the following command in the terminal:

jupyter notebook

Afterwards, a new website will open in your browser, where you can navigate to the examples directory and open the desired Notebook.

Adding Examples

If you want to add a new example, you can do so by creating a new Notebook in the examples directory. After creating and testing the example you need to convert it to the Myst Markdown format. For this step we use the jupytext tool. To convert a Notebook to Myst Markdown, run the following command in the examples directory of the project:

jupytext --to markdown your_notebook.ipynb

Linking directly to source code

Since the examples are stored as Myst Markdown files, you can link directly to the source code documentation. For example, to link to the source code of the class PickUpAction you can use:

{class}`~pycram.designators.action_designator.PickUpAction`

Alternatively, you can use {meth}, {func}, {attr}, {class}, {mod} and {obj} to link to methods, functions, attributes, classes, modules and objects, respectively.