1<?xml version="1.0" encoding="UTF-8"?> 2 3<!-- This is an automatically generated file. --> 4<Chapter Label="Intro"> 5<Heading>Introduction</Heading> 6 7<Section> 8<Heading>GAP Jupyter Kernel</Heading> 9 10This package provides a so-called <E>kernel</E> for the 11<URL Text="Jupyter">https://jupyter.org</URL> interactive document system. 12 13This kernel is implemented in &GAP;. 14 15</Section> 16 17 18<Section> 19<Heading>Installation</Heading> 20 21This package requires &Jupyter; to be installed on your system, which 22on most Python installations can be achieved by issuing the following command. 23<Log> 24> pip install --user notebook 25</Log> 26Further instructions can be found at <URL>https://jupyter.org/install</URL>. 27This package requires the &GAP; packages &IO;, &uuid;, &ZeroMQInterface;, 28&crypting;, and &json;, all of which are distributed with &GAP;, and some of which 29require compilation. 30To compile &ZeroMQInterface; you need to install &ZeroMQ;, for details please refer to the 31<URL Text="ZeroMQInterface manual">https://gap-packages.github.io/ZeroMQInterface/doc/chap0.html</URL>. 32 33&JupyterKernel; itself does not contain any kernel code that needs to be compiled. 34 35It is necessary to register &JupyterKernel; with your &Jupyter; installation. 36 37Registering the GAP jupyter kernel system-wide works as follows: 38<Log> 39> python setup.py install 40</Log> 41 42or registering for your user only 43 44<Log> 45> python setup.py install --user 46</Log> 47 48If &GAP; is not in your PATH, then you have to set the environment variable 49<C>JUPYTER_GAP_EXECUTABLE</C> to point to your GAP executable for &Jupyter; to 50be able to execute &GAP;, and the script <C>jupyter-kernel-gap</C> that is 51distributed with this package in the directory <C>bin/</C> needs to be in 52your path. 53 54To start &Jupyter; run: 55<Log> 56> jupyter notebook 57</Log> 58Then &JupyterKernel; should show up in your &Jupyter; installation as "GAP 4". 59 60</Section> 61 62<Section> 63<Heading>How it works</Heading> 64 65<Subsection> 66 <Heading>Kernel Startup</Heading> 67 68 This section gives a short explanation how the process of executing &GAP; as a 69 kernel by &Jupyter; works to help with debugging issues. 70 71 &Jupyter; registers kernels using json files in various directories. You can 72 list which kernel specifications are installed by executing the following 73 command 74 75 <Log> 76 > jupyter kernelspec list 77 Available kernels: 78 python2 /usr/local/lib/python2.7/site-packages/ipykernel/resources 79 gap-4 /usr/local/share/jupyter/kernels/gap-4 80 </Log> 81 82 If there is no line containing the <C>gap-4</C> kernel, something went 83 wrong with <C>setup.py</C>. You can try to manually install the file 84 <C>kernel.json</C> which is in the <C>etc</C> directory of the &JupyterKernel; 85 package by copying it. Better yet, you should report this issue on the issue 86 tracker giving wich operating system you are using, your version of &Jupyter; 87 and &GAP;, and which commands you tried to execute. 88 89 What happens when &Jupyter; wants to start a &GAP; kernel is that it tries 90 to execute the small script <C>jupyter-kernel-gap</C> (which is distributed with 91 the &JupyterKernel; package), which in turn executes &GAP;, loading the package 92 and then running the kernel. This script currently has to be in your <C>PATH</C> 93 environment variable, too. 94</Subsection> 95 96<Subsection> 97 <Heading>Kernel operation</Heading> 98 99 The communication between the &Jupyter; frontend and &GAP; happens through ZeroMQ streams 100 as documented 101 <URL Text="here">http://jupyter-client.readthedocs.io/en/latest/messaging.html</URL>, 102 encoded as <C>JSON</C> dicts. 103 104 After entering code into a cell and instructing &Jupyter; to execute that code, 105 the jupyter frontend sends the code to the &GAP; session where it is executed by 106 using the &GAP; function <C>READ_ALL_COMMANDS</C>, resulting values of the 107 execution are rendered using <C>ViewString</C> and sent back to the &Jupyter; 108 frontend. 109 110 In principle, rich rendering of content, as exemplified in the function 111 <C>JUPYTER_DotSplash</C> is possible. 112 113 Tab-completion is handled by the &GAP; function <C>JUPYTER_completion</C>, and 114 inspection is handled by <C>JUPYTER_Inspect</C>. 115 116 Changing these functions, one can change the behaviour of Tab-completion and 117 inspection to improve user experience. 118</Subsection> 119</Section> 120 121<Section Label="Code Highlighting and Indentation"> 122 <Heading>Code Highlighting and Indentation</Heading> 123 124 &JupyterKernel; provides a &GAP; mode with code highlighting and indentation. 125 This mode is installed as a notebook extension and registers 'text/x-gap' as 126 a MIME type. 127 128</Section> 129 130<Section Label="Known Limitations and Caveats"> 131 <Heading>Known Limitations and Caveats</Heading> 132 133 Currently the support of the &GAP; system for alternative frontends is 134 a work in progress. In particular, certain outputs that are 135 printed by &GAP; cannot be captured by the &Jupyter; frontend and will 136 not show up. 137 138 If you happen to notice problems of this kind, feel free to report them 139 on the <URL Text="issue tracker">https://github.com/gap-packages/JupyterKernel/issues</URL>. 140 or suggest a solution via a pull-request. 141</Section> 142 143<Section Label="feedback"> 144<Heading>Feedback</Heading> 145 146For bug reports, feature requests and suggestions, please use our 147<URL Text="issue tracker">https://github.com/gap-packages/JupyterKernel/issues</URL>. 148 149</Section> 150 151 152</Chapter> 153