Skip to content

Commit aa5920c

Browse files
EricCousineau-TRIEricCousineau-TRI
authored
Add simple example Jupyter notebook (for Binder) (#127)
* examples: Add Binder-compatible Jupyter notebook example * TO BE SQUASHED jupyterlab * try jupyterlab * give up on JupyterLab; leave as TODO * address review * address review * address review
1 parent f399f97 commit aa5920c

File tree

7 files changed

+251
-6
lines changed

7 files changed

+251
-6
lines changed

‎.binder/.dockerignore

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
README.md

‎.binder/Dockerfile

+65
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# -*- mode: dockerfile -*-
2+
# vi: set ft=dockerfile :
3+
4+
# TODO(eric.cousineau): Figure out how to make JupyterLab work with this setup:
5+
# https://github.com/binder-examples/jupyterlab
6+
7+
# TODO(eric.cousineau): See if it's easier to use a conda-based workflow, or a
8+
# simpler Docker base image, to use Eigen headers, rather than doing a custom
9+
# Docker image:
10+
# https://mybinder.readthedocs.io/en/latest/using/config_files.html
11+
12+
FROM ubuntu:18.04
13+
14+
ARG NB_USER=jovyan
15+
ARG NB_UID=1000
16+
ARG NB_GID=100
17+
EXPOSE 7000/tcp
18+
EXPOSE 8888/tcp
19+
20+
RUN export DEBIAN_FRONTEND=noninteractive \
21+
&& apt-get update \
22+
&& apt-get install -y --no-install-recommends \
23+
-o Dpkg::Options::=--force-confdef -o Dpkg::Options::=--force-confnew \
24+
-o Dpkg::Use-Pty=0 \
25+
locales \
26+
python3-pip \
27+
python3-setuptools \
28+
&& rm -rf /var/lib/apt/lists/* \
29+
&& locale-gen en_US.UTF-8
30+
31+
# Install common C++ libraries for experimenting. These are not necessary to
32+
# use pygccxml itself.
33+
RUN export DEBIAN_FRONTEND=noninteractive \
34+
&& apt-get update \
35+
&& apt-get install -y --no-install-recommends \
36+
-o Dpkg::Options::=--force-confdef -o Dpkg::Options::=--force-confnew \
37+
-o Dpkg::Use-Pty=0 \
38+
libeigen3-dev \
39+
libstdc++-7-dev \
40+
&& rm -rf /var/lib/apt/lists/*
41+
42+
RUN useradd -d "/home/$NB_USER" -G $NB_GID -mU -s /bin/bash "$NB_USER"
43+
ENV HOME="/home/$NB_USER" \
44+
LANG=en_US.UTF-8 \
45+
LANGUAGE=en_US.UTF-8 \
46+
LC_ALL=en_US.UTF-8 \
47+
SHELL=/bin/bash \
48+
USER="$NB_USER" \
49+
PATH="/home/$NB_USER/.local/bin:/usr/local/bin:/usr/bin:/bin"
50+
51+
# Upgrade pip to use newer indices for castxml.
52+
# WARNING: Never upgrade a distribution `pip` on a host system using sudo!
53+
# We are only doing this for a transient Docker image. For a host system, use a
54+
# virtualenv to upgrade pip.
55+
RUN pip3 --no-cache-dir install -U pip
56+
57+
WORKDIR $HOME
58+
RUN mkdir pygccxml
59+
COPY ["/", "pygccxml/"]
60+
RUN chown -R $NB_UID:$NB_GID \
61+
"$HOME/pygccxml"
62+
USER "$NB_USER"
63+
RUN pip3 --no-cache-dir install castxml
64+
RUN pip3 --no-cache-dir install -e ./pygccxml[examples]
65+
CMD ["jupyter", "notebook", "--ip", "0.0.0.0", "pygccxml/docs/examples/notebook/example.ipynb"]

‎.binder/README.md

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Docker Image for Binder
2+
3+
<!--
4+
This is derived from the following setup:
5+
https://github.com/RobotLocomotion/drake/tree/dc2a9394d/.binder
6+
-->
7+
8+
*Note that due to Binder conventions, this directory MUST always be in the root
9+
of the repository and named either `binder` or `.binder`. This image is NOT
10+
intended for use by most developers or users.*
11+
12+
These instructions are for running the image locally. For Binder itself, you
13+
should only need to visit the link from the root-level README.
14+
15+
To create a Docker image and run a Docker container similar to those used by
16+
[Binder](https://mybinder.org) for local debugging purposes, execute the
17+
following `build` and `run` commands from the top level of this Git repository:
18+
19+
```bash
20+
docker build -f .binder/Dockerfile -t binder .
21+
docker run --rm -it --name mybinder -p 8888:8888 binder
22+
```
23+
24+
For the URLs printed, only open the `127.0.0.1:8888` URL (including the login
25+
token) in a web browser on your host system.
26+
27+
To stop the running container, simply exit it from the terminal with Ctrl+C.
28+
29+
*Note*: If you want to test the Docker image with the current source tree
30+
(without copying, so you can modify source files), insert the arguments
31+
`-v "${PWD}:/home/jovyan/pygccxml"` to `docker run`, before the image name
32+
(`binder`), to mount it directly. This will *not* act on any changes to
33+
`./setup.py`.

‎.dockerignore

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.gitignore

‎README.rst

+14
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,23 @@ Documentation and examples
3333
--------------------------
3434

3535
The documentation can be found `here <http://pygccxml.readthedocs.io>`_, examples can be found `here <http://pygccxml.readthedocs.io/en/master/examples.html>`_.
36+
You can also run an example JupyterLab Notebook using Binder, or view it using
37+
``nbviewer``:
38+
39+
..
40+
Developers: See `.binder/README.md` for more information.
41+
42+
.. image:: https://mybinder.org/badge_logo.svg
43+
:target: https://mybinder.org/v2/gh/EricCousineau-TRI/pygccxml/feature-py-notebook-example?urlpath=tree/pygccxml/docs/examples/notebook/
44+
:alt: Binder
45+
.. image:: https://img.shields.io/badge/view%20on-nbviewer-brightgreen.svg
46+
:target: https://nbviewer.jupyter.org/github/EricCousineau-TRI/pygccxml/tree/feature-py-notebook-example/docs/examples/notebook/
47+
:alt: nbviewer
3648

3749
If you want to know more about the API provided by pygccxml, read the `query interface <http://pygccxml.readthedocs.io/en/develop/query_interface.html>`_ document or the `API documentation <http://pygccxml.readthedocs.io/en/develop/apidocs/modules.html>`_.
3850

51+
52+
3953
A `FAQ <http://pygccxml.readthedocs.io/en/master/faq.html>`_ is also available and may answer some of your questions.
4054

4155
License

‎docs/examples/notebook/example.ipynb

+127
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"# Example pygccxml notebook on Binder\n",
8+
"\n",
9+
"Running this notebook on Binder allows you to execute the code online:",
10+
"<a target=\"_doc\" href=\"https://mybinder.org/v2/gh/EricCousineau-TRI/pygccxml/feature-py-notebook-example?urlpath=tree/pygccxml/docs/examples/notebook/example.ipynb\">\n",
11+
" <img src=\"https://mybinder.org/badge_logo.svg\"/>\n",
12+
"</a>\n",
13+
"\n",
14+
"Please note that provisioning may take about 1-2 minutes.\n",
15+
"\n",
16+
"\n",
17+
"The following example shows an example usage of `pygccxml` on Ubuntu\n",
18+
"Bionic, from within a Docker container, for a simple toy C++ API that\n",
19+
"uses both `std::vector` and `Eigen::Matrix<>`. The code is defined inline."
20+
]
21+
},
22+
{
23+
"cell_type": "code",
24+
"execution_count": null,
25+
"metadata": {},
26+
"outputs": [],
27+
"source": [
28+
"from pygccxml import declarations\n",
29+
"from pygccxml import utils\n",
30+
"from pygccxml import parser"
31+
]
32+
},
33+
{
34+
"cell_type": "code",
35+
"execution_count": null,
36+
"metadata": {},
37+
"outputs": [],
38+
"source": [
39+
"# Find out the c++ parser. This should resolve to the castxml\n",
40+
"# version installed in Docker.\n",
41+
"generator_path, generator_name = utils.find_xml_generator()\n",
42+
"\n",
43+
"# Configure the xml generator\n",
44+
"config = parser.xml_generator_configuration_t(\n",
45+
" xml_generator_path=generator_path,\n",
46+
" xml_generator=generator_name,\n",
47+
" include_paths=[\"/usr/include/eigen3\"],\n",
48+
" compiler_path=generator_path,\n",
49+
")"
50+
]
51+
},
52+
{
53+
"cell_type": "code",
54+
"execution_count": null,
55+
"metadata": {},
56+
"outputs": [],
57+
"source": [
58+
"code = r\"\"\"\n",
59+
"#include <vector>\n",
60+
"\n",
61+
"#include <Eigen/Dense>\n",
62+
"\n",
63+
"namespace ns {\n",
64+
"\n",
65+
"template <typename T, typename U = int>\n",
66+
"class ExampleClass {\n",
67+
"public:\n",
68+
" std::vector<T> make_std_vector() const;\n",
69+
" Eigen::Matrix<U, 3, 3> make_matrix3();\n",
70+
"};\n",
71+
"\n",
72+
"// Analyze concrete instantiations of the given class.\n",
73+
"extern template class ExampleClass<int>;\n",
74+
"extern template class ExampleClass<float, float>;\n",
75+
"\n",
76+
"} // namespace ns\n",
77+
"\"\"\"\n",
78+
"\n",
79+
"(global_ns,) = parser.parse_string(code, config)"
80+
]
81+
},
82+
{
83+
"cell_type": "code",
84+
"execution_count": null,
85+
"metadata": {
86+
"scrolled": false
87+
},
88+
"outputs": [],
89+
"source": [
90+
"ns = global_ns.namespace(\"ns\")\n",
91+
"declarations.print_declarations([ns])"
92+
]
93+
},
94+
{
95+
"cell_type": "code",
96+
"execution_count": null,
97+
"metadata": {},
98+
"outputs": [],
99+
"source": [
100+
"# Retrieve an instantiation and show template parameters.\n",
101+
"cls, = ns.classes('ExampleClass<float, float>')\n",
102+
"declarations.templates.split(cls.name)"
103+
]
104+
}
105+
],
106+
"metadata": {
107+
"kernelspec": {
108+
"display_name": "Python 3",
109+
"language": "python",
110+
"name": "python3"
111+
},
112+
"language_info": {
113+
"codemirror_mode": {
114+
"name": "ipython",
115+
"version": 3
116+
},
117+
"file_extension": ".py",
118+
"mimetype": "text/x-python",
119+
"name": "python",
120+
"nbconvert_exporter": "python",
121+
"pygments_lexer": "ipython3",
122+
"version": "3.6.9"
123+
}
124+
},
125+
"nbformat": 4,
126+
"nbformat_minor": 4
127+
}

‎setup.py

+10-6
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,18 @@
99

1010
version = utils.find_version("../pygccxml/__init__.py")
1111

12-
requirements_test = {
12+
requirements_test = [
1313
"coverage",
1414
"coveralls",
1515
"pycodestyle",
16-
}
17-
requirements_docs = {
16+
]
17+
requirements_docs = [
1818
"sphinx",
1919
"sphinx_rtd_theme",
20-
}
20+
]
21+
requirements_examples = [
22+
"notebook",
23+
]
2124

2225
setup(name="pygccxml",
2326
version=version,
@@ -36,8 +39,9 @@
3639
"pygccxml.parser",
3740
"pygccxml.utils"],
3841
extras_require={
39-
"test": list(requirements_test),
40-
"docs": list(requirements_docs),
42+
"test": requirements_test,
43+
"docs": requirements_docs,
44+
"examples": requirements_examples,
4145
},
4246
classifiers=[
4347
"Development Status :: 5 - Production/Stable",

0 commit comments

Comments
 (0)