diff --git a/.gitattributes b/.gitattributes index 6f7f8bc..832e560 100644 --- a/.gitattributes +++ b/.gitattributes @@ -2,3 +2,6 @@ artefacts/** linguist-generated * text=lf * eol=lf + +*.png binary +*.jpg binary diff --git a/Makefile b/Makefile index fdc2d58..1dc2793 100644 --- a/Makefile +++ b/Makefile @@ -56,6 +56,11 @@ primitives: artefacts/trames.json @ python generators/generate_primitives.py +.PHONY: doc +doc: + $(MAKE) -C docs html + + V ?= 0 ifneq ($(V),0) Q := diff --git a/artefacts/docs/trames.rst b/artefacts/docs/trames.rst new file mode 100644 index 0000000..c31a826 --- /dev/null +++ b/artefacts/docs/trames.rst @@ -0,0 +1,160 @@ +======================== +ILO Trame Specification +======================== + +This table is generated automatically from ``trame.json``. + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + :class: ilo-trame-table + + * - **Name** + - **Trame Format** + + * - ``safety_stop`` + - ``<>`` + * - ``handshake_ilo`` + - ```` + * - ``get_robot_version`` + - ``<500y>`` + * - ``start_firmware_upload`` + - ``<500x[size]>`` + * - ``start_trame_s`` + - ``<0[trame_s_params]>`` + * - ``stop_tasks`` + - ``<00>`` + * - ``get_color_rgb_center`` + - ``<10c>`` + * - ``get_color_rgb_left`` + - ``<10l>`` + * - ``get_color_rgb_right`` + - ``<10d>`` + * - ``get_color_clear`` + - ``<11>`` + * - ``get_line`` + - ``<12>`` + * - ``set_line_threshold_value`` + - ``<13t[threshold]>`` + * - ``get_line_threshold_value`` + - ``<14>`` + * - ``get_accessory_status`` + - ``<15>`` + * - ``get_sensor_distance`` + - ``<20>`` + * - ``get_distance_front`` + - ``<21>`` + * - ``get_distance_right`` + - ``<22>`` + * - ``get_distance_back`` + - ``<23>`` + * - ``get_distance_left`` + - ``<24>`` + * - ``get_imu_info`` + - ``<30>`` + * - ``reset_angle`` + - ``<31>`` + * - ``get_raw_imu`` + - ``<32>`` + * - ``get_battery_info`` + - ``<40>`` + * - ``get_led_color`` + - ``<50>`` + * - ``set_led_color`` + - ``<51r[red]g[green]b[blue]>`` + * - ``set_led_shape`` + - ``<52v[shape]>`` + * - ``set_led_mode`` + - ``<53[mode]/[nb_loop]>`` + * - ``set_led_captor`` + - ``<54l[brightness]>`` + * - ``set_led_single`` + - ``<55t[type]d[id]r[red]g[green]b[blue]>`` + * - ``display_word`` + - ``<56w[word]d[delay]/[nb_loops]>`` + * - ``display_word_slide`` + - ``<57>`` + * - ``set_animation_flag_false`` + - ``<58>`` + * - ``run_command_motor`` + - ```` + * - ``ping_motor`` + - ``<60i[ping_status_0]s[ping_status_1]>`` + * - ``drive_single_motor_speed`` + - ``<610i[motor_index]a[acc]v[speed]>`` + * - ``get_single_motor_speed`` + - ``<611i[motor_index]>`` + * - ``drive_single_motor_angle`` + - ``<620i[motor_index]a[acc]v[vel]p[position]>`` + * - ``get_single_motor_angle`` + - ``<621i[motor_index]>`` + * - ``get_single_motor_temp`` + - ``<63i[motor_index]>`` + * - ``get_single_motor_volt`` + - ``<64i[motor_index]>`` + * - ``get_single_motor_load`` + - ``<65i[motor_index]>`` + * - ``get_single_motor_current`` + - ``<66i[motor_index]>`` + * - ``get_single_motor_move`` + - ``<67i[motor_index]>`` + * - ``set_motors_ilo_acc`` + - ``<680a[acc]>`` + * - ``get_motors_ilo_acc`` + - ``<681>`` + * - ``set_tempo_pos`` + - ``<690t[tempo_pos]>`` + * - ``get_tempo_pos`` + - ``<691>`` + * - ``set_pid`` + - ``<70p[Kp]i[Ki]d[Kd]>`` + * - ``get_pid`` + - ``<71>`` + * - ``check_auto_mode`` + - ``<80[current_auto_mode]>`` + * - ``set_wifi_credentials`` + - ``<90[ssid]{|||}[password]>`` + * - ``get_wifi_credentials`` + - ``<92>`` + * - ``get_hostname`` + - ``<93>`` + * - ``get_hostname_legacy`` + - ``<930>`` + * - ``set_name`` + - ``<94n[name]>`` + * - ``set_server_status`` + - ``<95s[status]>`` + * - ``get_server_status`` + - ``<96>`` + * - ``get_accessory_data`` + - ``<100>`` + * - ``get_accessory_info`` + - ``<101>`` + * - ``very_very_usefull`` + - ``<102>`` + * - ``set_debug_state`` + - ``<103s[state]>`` + * - ``start_diag`` + - ``<110>`` + * - ``get_manufacturing_date`` + - ``<120>`` + * - ``set_manufacturing_date`` + - ``<121s[date]>`` + * - ``get_first_use_date`` + - ``<130>`` + * - ``set_first_use_date`` + - ``<131s[date]>`` + * - ``get_product_version`` + - ``<140>`` + * - ``set_product_version`` + - ``<141s[version]>`` + * - ``get_product_id`` + - ``<150>`` + * - ``set_product_id`` + - ``<151s[product_id]>`` + * - ``get_review_date`` + - ``<160>`` + * - ``set_review_date`` + - ``<161s[date]>`` + * - ``set_auto_setup`` + - ``<170a[auto_setup]>`` diff --git a/artefacts/python/trame_builder.rst b/artefacts/python/trame_builder.rst new file mode 100644 index 0000000..1930a96 --- /dev/null +++ b/artefacts/python/trame_builder.rst @@ -0,0 +1,517 @@ +Python Primitives API +===================== + +This section documents the generated Python primitives. + + + +.. py:function:: safety_stop() + + Primitive for safety_stop + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: handshake_ilo() + + Primitive for handshake_ilo + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_robot_version() + + Primitive for get_robot_version + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: start_firmware_upload(size: int) + + Primitive for start_firmware_upload + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: start_trame_s(trame_s_params: str) + + Primitive for start_trame_s + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: stop_tasks() + + Primitive for stop_tasks + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_color_rgb_center() + + Primitive for get_color_rgb_center + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_color_rgb_left() + + Primitive for get_color_rgb_left + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_color_rgb_right() + + Primitive for get_color_rgb_right + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_color_clear() + + Primitive for get_color_clear + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_line() + + Primitive for get_line + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: set_line_threshold_value(threshold: int) + + Primitive for set_line_threshold_value + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_line_threshold_value() + + Primitive for get_line_threshold_value + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_accessory_status() + + Primitive for get_accessory_status + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_sensor_distance() + + Primitive for get_sensor_distance + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_distance_front() + + Primitive for get_distance_front + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_distance_right() + + Primitive for get_distance_right + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_distance_back() + + Primitive for get_distance_back + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_distance_left() + + Primitive for get_distance_left + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_imu_info() + + Primitive for get_imu_info + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: reset_angle() + + Primitive for reset_angle + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_raw_imu() + + Primitive for get_raw_imu + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_battery_info() + + Primitive for get_battery_info + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_led_color() + + Primitive for get_led_color + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: set_led_color(red: int, green: int, blue: int) + + Primitive for set_led_color + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: set_led_shape(shape: str) + + Primitive for set_led_shape + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: set_led_mode(mode: str, nb_loop: int) + + Primitive for set_led_mode + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: set_led_captor(brightness: int) + + Primitive for set_led_captor + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: set_led_single(type: str, id: int, red: int, green: int, blue: int) + + Primitive for set_led_single + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: display_word(word: str, delay: int, nb_loops: int) + + Primitive for display_word + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: display_word_slide() + + Primitive for display_word_slide + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: set_animation_flag_false() + + Primitive for set_animation_flag_false + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: run_command_motor(params: str) + + Primitive for run_command_motor + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: ping_motor(ping_status_0: int, ping_status_1: int) + + Primitive for ping_motor + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: drive_single_motor_speed(motor_index: int, acc: int, speed: int) + + Primitive for drive_single_motor_speed + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_single_motor_speed(motor_index: int) + + Primitive for get_single_motor_speed + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: drive_single_motor_angle(motor_index: int, acc: int, vel: int, position: int) + + Primitive for drive_single_motor_angle + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_single_motor_angle(motor_index: int) + + Primitive for get_single_motor_angle + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_single_motor_temp(motor_index: int) + + Primitive for get_single_motor_temp + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_single_motor_volt(motor_index: int) + + Primitive for get_single_motor_volt + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_single_motor_load(motor_index: int) + + Primitive for get_single_motor_load + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_single_motor_current(motor_index: int) + + Primitive for get_single_motor_current + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_single_motor_move(motor_index: int) + + Primitive for get_single_motor_move + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: set_motors_ilo_acc(acc: int) + + Primitive for set_motors_ilo_acc + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_motors_ilo_acc() + + Primitive for get_motors_ilo_acc + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: set_tempo_pos(tempo_pos: int) + + Primitive for set_tempo_pos + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_tempo_pos() + + Primitive for get_tempo_pos + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: set_pid(Kp: int, Ki: int, Kd: int) + + Primitive for set_pid + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_pid() + + Primitive for get_pid + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: check_auto_mode(current_auto_mode: int) + + Primitive for check_auto_mode + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: set_wifi_credentials(ssid: str, password: str) + + Primitive for set_wifi_credentials + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_wifi_credentials() + + Primitive for get_wifi_credentials + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_hostname() + + Primitive for get_hostname + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_hostname_legacy() + + Primitive for get_hostname_legacy + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: set_name(name: str) + + Primitive for set_name + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: set_server_status(status: int) + + Primitive for set_server_status + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_server_status() + + Primitive for get_server_status + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_accessory_data() + + Primitive for get_accessory_data + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_accessory_info() + + Primitive for get_accessory_info + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: very_very_usefull() + + Primitive for very_very_usefull + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: set_debug_state(state: int) + + Primitive for set_debug_state + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: start_diag() + + Primitive for start_diag + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_manufacturing_date() + + Primitive for get_manufacturing_date + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: set_manufacturing_date(date: str) + + Primitive for set_manufacturing_date + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_first_use_date() + + Primitive for get_first_use_date + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: set_first_use_date(date: str) + + Primitive for set_first_use_date + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_product_version() + + Primitive for get_product_version + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: set_product_version(version: str) + + Primitive for set_product_version + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_product_id() + + Primitive for get_product_id + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: set_product_id(product_id: str) + + Primitive for set_product_id + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: get_review_date() + + Primitive for get_review_date + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: set_review_date(date: str) + + Primitive for set_review_date + + **Returns:** ``str`` — the encoded trame. + + +.. py:function:: set_auto_setup(auto_setup: int) + + Primitive for set_auto_setup + + **Returns:** ``str`` — the encoded trame. + diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..40098da --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = ../.build/doc + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/favicon.png b/docs/_static/favicon.png new file mode 100644 index 0000000..2de2f87 Binary files /dev/null and b/docs/_static/favicon.png differ diff --git a/docs/_static/ilo.png b/docs/_static/ilo.png new file mode 100644 index 0000000..7e9ad67 Binary files /dev/null and b/docs/_static/ilo.png differ diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 0000000..b6e1cd5 --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,8 @@ +API +=== + +.. toctree:: + :maxdepth: 1 + + python/trame_builder + trames diff --git a/docs/api/python/trame_builder.rst b/docs/api/python/trame_builder.rst new file mode 120000 index 0000000..3cd8eb3 --- /dev/null +++ b/docs/api/python/trame_builder.rst @@ -0,0 +1 @@ +../../../artefacts/python/trame_builder.rst \ No newline at end of file diff --git a/docs/api/trames.rst b/docs/api/trames.rst new file mode 120000 index 0000000..e6106c5 --- /dev/null +++ b/docs/api/trames.rst @@ -0,0 +1 @@ +../../artefacts/docs/trames.rst \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..fd35531 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,23 @@ +import os +import sys + +# Allow `import ilo_primitives` if needed +sys.path.insert(0, os.path.abspath('../artefacts/primitives/python')) + +project = "Ilo Libs" +copyright = author = "Intuition-rt" + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.extlinks", + "sphinx.ext.napoleon", + "sphinx.ext.viewcode", +] + +templates_path = ["_templates"] +html_static_path = ["_static"] + +html_title = project +html_theme = "furo" +html_logo = "_static/ilo.png" +html_favicon = "_static/favicon.png" diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..7638a4e --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,16 @@ +Documentation +============= + +Table of content +---------------- + +.. toctree:: + :maxdepth: 2 + + api/index + + +.. toctree:: + :maxdepth: 10 + :caption: Reference + :hidden: diff --git a/flake.nix b/flake.nix index 910549e..f8032f0 100644 --- a/flake.nix +++ b/flake.nix @@ -24,7 +24,7 @@ clang-tools scom compiledb - (python3.withPackages (p: [ p.jinja2 ])) + (python3.withPackages (p: with p; [ jinja2 sphinx furo ])) ]; env.NIX_CFLAGS_COMPILE = diff --git a/generators/generate_primitives.py b/generators/generate_primitives.py index f0aa500..b8ffc4e 100644 --- a/generators/generate_primitives.py +++ b/generators/generate_primitives.py @@ -70,9 +70,23 @@ def escape_fstring_literal(s: str) -> str: return s.replace("{", "{{").replace("}", "}}") +def format_trame(trame: Trame): + parts = [] + + for part, param in zip(trame["trame_parts"], trame["parameters"]): + parts.append(f'{part}[{param["name"]}]') + + if len(trame["trame_parts"]) > len(trame["parameters"]): + parts.append(trame["trame_parts"][-1]) + + + return '``<' + "".join(parts) + '>``' + + def main(): with TRAMES_JSON.open() as f: - trames_list = [rework_trame(trame) for trame in json.load(f)] + trames_formats = json.load(f) + trames = [rework_trame(trame) for trame in trames_formats] env = Environment( loader=FileSystemLoader(TEMPLATES_DIR), @@ -81,6 +95,7 @@ def main(): ) env.filters["escape_fstring"] = escape_fstring_literal + env.filters["format_trame"] = format_trame jinja_templates_per_langs = ( (lang_dir, template_file) @@ -96,7 +111,8 @@ def main(): template = env.get_template(str(rel_path)) rendered = template.render( - trames=trames_list, + trames=trames, + trames_formats=trames_formats, lang=lang_dir.name ) diff --git a/generators/templates/docs/trames.rst.jinja b/generators/templates/docs/trames.rst.jinja new file mode 100644 index 0000000..f27ea57 --- /dev/null +++ b/generators/templates/docs/trames.rst.jinja @@ -0,0 +1,18 @@ +======================== +ILO Trame Specification +======================== + +This table is generated automatically from ``trame.json``. + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + :class: ilo-trame-table + + * - **Name** + - **Trame Format** + + {% for t in trames %} + * - ``{{ t.name }}`` + - {{ t | format_trame }} + {% endfor %} diff --git a/generators/templates/python/trame_builder.rst.jinja b/generators/templates/python/trame_builder.rst.jinja new file mode 100644 index 0000000..17377b1 --- /dev/null +++ b/generators/templates/python/trame_builder.rst.jinja @@ -0,0 +1,21 @@ +Python Primitives API +===================== + +This section documents the generated Python primitives. + +{% set type_map = { + "boolean": "bool", + "integer": "int", + "string": "str", + "float": "float" +} %} + +{% for t in trames %} + +.. py:function:: {{ t.name }}({% for p in t.parameters %}{{ p.name }}: {{ type_map[p.type] }}{% if not loop.last %}, {% endif %}{% endfor %}) + + {{ t.doc or "Primitive for " ~ t.name }} + + **Returns:** ``str`` — the encoded trame. + +{% endfor %}