From 0fb27f0563131b71a3124c0d35e47fcb074e58b9 Mon Sep 17 00:00:00 2001 From: pelikhan Date: Thu, 18 Nov 2021 13:50:46 -0800 Subject: [PATCH] another attempt at fixing docs --- .gitignore | 2 + docs/Makefile | 20 +++++++++ docs/api.rst | 15 +++---- docs/conf.py | 50 ++++++++++++++++------ docs/index.rst | 4 +- docs/make.bat | 35 +++++++++++++++ docs/requirements.txt | 3 +- docs/usage.rst | 21 +-------- jacdac/barometer/test.py | 27 ++++++------ jacdac/button/test.py | 34 +++++++-------- jacdac/hid_adapter/__init__.py | 2 - jacdac/hid_adapter/client.py | 76 --------------------------------- jacdac/hid_adapter/constants.py | 20 --------- jacdac/relay/test.py | 34 +++++++-------- test.py | 3 +- 15 files changed, 150 insertions(+), 196 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/make.bat delete mode 100644 jacdac/hid_adapter/__init__.py delete mode 100644 jacdac/hid_adapter/client.py delete mode 100644 jacdac/hid_adapter/constants.py diff --git a/.gitignore b/.gitignore index b6e4761..c9a7e24 100644 --- a/.gitignore +++ b/.gitignore @@ -127,3 +127,5 @@ dmypy.json # Pyre type checker .pyre/ + +docs/generated/ \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /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 + +# 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/api.rst b/docs/api.rst index 8e0bb6c..f365e87 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,13 +1,8 @@ +API +=== + .. autosummary:: + :toctree: generated :recursive: - jacdac - -.. automodule:: jacdac - :members: - -.. automodule:: jacdac.bus - :members: - -.. automodule:: jacdac.button - :members: + jacdac \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index bba0b19..2185c21 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,39 +1,63 @@ # Configuration file for the Sphinx documentation builder. -# -- Project information +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# import os import sys -sys.path.insert(0, os.path.abspath('../jacdac')) +sys.path.insert(0, os.path.abspath('..')) + + +# -- Project information ----------------------------------------------------- project = 'Jacdac Python' copyright = '2021, Microsoft Corporation' -author = 'Microsoft' +author = 'Microsoft Corporation' -release = '0.1' -version = '0.1.0' +# The full version, including alpha/beta/rc tags +release = '0.0.0' -# -- General configuration +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. extensions = [ + 'myst_parser', 'sphinx.ext.duration', 'sphinx.ext.doctest', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', - 'sphinx.ext.intersphinx', - "sphinx.ext.viewcode", + 'sphinx.ext.intersphinx', ] intersphinx_mapping = { 'python': ('https://docs.python.org/3/', None), 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), - 'jacdac': ('https://aka.ms/jacdac/', None) } intersphinx_disabled_domains = ['std'] +# Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + # -- Options for HTML output - html_theme = 'sphinx_rtd_theme' - -# -- Options for EPUB output -epub_show_urls = 'footnote' +html_theme_path = ["_themes", ] \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 83783c4..271b907 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,5 @@ -Welcome to Jacdac-Python's documentation! -========================================= +Welcome to Jacdac Python documentation! +======================================= **Jacdac** is a plug-and-play hardware/software stack for **microcontrollers** and their peripherals (sensors/actuators), diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..153be5e --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt index 5215769..6692370 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1 +1,2 @@ -sphinx>=4.0.0 +myst-parser +sphinx-rtd-theme \ No newline at end of file diff --git a/docs/usage.rst b/docs/usage.rst index 7975c44..c1e9f87 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -6,28 +6,9 @@ Usage Installation ------------ -To use Jacdac-Python, first install it using pip: +To use Lumache, first install it using pip: .. code-block:: console (.venv) $ pip install jacdac-python -Creating recipes ----------------- - -To retrieve a list of random ingredients, -you can use the ``lumache.get_random_ingredients()`` function: - -.. autofunction:: lumache.get_random_ingredients - -The ``kind`` parameter should be either ``"meat"``, ``"fish"``, -or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients` -will raise an exception. - -.. autoexception:: lumache.InvalidKindError - -For example: - ->>> import lumache ->>> lumache.get_random_ingredients() -['shells', 'gorgonzola', 'parsley'] diff --git a/jacdac/barometer/test.py b/jacdac/barometer/test.py index 2dee068..cee6d23 100644 --- a/jacdac/barometer/test.py +++ b/jacdac/barometer/test.py @@ -3,22 +3,19 @@ from jacdac.devtools import create_dev_tools_bus from .client import BarometerClient from time import sleep -bus = create_dev_tools_bus() +if __name__ == '__main__': + bus = create_dev_tools_bus() + def up(data: Any): + print("up") -def up(data: Any): - print("up") + def down(data: Any): + print("down") + def hold(data: list[Type[int]]): + print("hold", data[0]) -def down(data: Any): - print("down") - - -def hold(data: list[Type[int]]): - print("hold", data[0]) - - -barometer = BarometerClient(bus, "barometer") -while True: - print("pressure: ", barometer.pressure, "e:", barometer.pressure_error) - sleep(0.2) + barometer = BarometerClient(bus, "barometer") + while True: + print("pressure: ", barometer.pressure, "e:", barometer.pressure_error) + sleep(0.2) diff --git a/jacdac/button/test.py b/jacdac/button/test.py index 26e39fd..19b454d 100644 --- a/jacdac/button/test.py +++ b/jacdac/button/test.py @@ -3,27 +3,25 @@ from jacdac.devtools import create_dev_tools_bus from .client import ButtonClient from time import sleep -bus = create_dev_tools_bus() +if __name__ == '__main__': + bus = create_dev_tools_bus() -def up(data: Any): - print("up") + def up(data: Any): + print("up") + def down(data: Any): + print("down") -def down(data: Any): - print("down") + def hold(data: list[Type[int]]): + print("hold", data[0]) + btn1 = ButtonClient(bus, "btn1") + btn1.on_up(up) + btn1.on_down(down) + btn1.on_hold(hold) -def hold(data: list[Type[int]]): - print("hold", data[0]) - - -btn1 = ButtonClient(bus, "btn1") -btn1.on_up(up) -btn1.on_down(down) -btn1.on_hold(hold) - -while True: - print("pressed: ", btn1.pressed) - print("pressure: ", btn1.pressure) - sleep(1) + while True: + print("pressed: ", btn1.pressed) + print("pressure: ", btn1.pressure) + sleep(1) diff --git a/jacdac/hid_adapter/__init__.py b/jacdac/hid_adapter/__init__.py deleted file mode 100644 index aeaca5a..0000000 --- a/jacdac/hid_adapter/__init__.py +++ /dev/null @@ -1,2 +0,0 @@ -# Autogenerated file. -from .client import * diff --git a/jacdac/hid_adapter/client.py b/jacdac/hid_adapter/client.py deleted file mode 100644 index ba07e1f..0000000 --- a/jacdac/hid_adapter/client.py +++ /dev/null @@ -1,76 +0,0 @@ -# Autogenerated file. Do not edit. -from jacdac.bus import Bus, Client -from .constants import * -from typing import Optional, cast -from jacdac.events import EventHandlerFn, UnsubscribeFn - -class HidAdapterClient(Client): - """ - A service for configuring how Jacdac device map to HID input events. Users can have multiple configurations and swap between them by writing to `current_configuration`. - """ - - def __init__(self, bus: Bus, role: str) -> None: - super().__init__(bus, JD_SERVICE_CLASS_HID_ADAPTER, JD_HID_ADAPTER_PACK_FORMATS, role) - - - @property - def num_configurations(self) -> Optional[int]: - """ - The number of configurations stored on the server., - """ - reg = self.register(JD_HID_ADAPTER_REG_NUM_CONFIGURATIONS) - values = reg.values() - return cast(Optional[int], values[0] if values else None) - - @num_configurations.setter - def num_configurations(self, value: int) -> None: - reg = self.register(JD_HID_ADAPTER_REG_NUM_CONFIGURATIONS) - reg.set_values(value) - - - @property - def current_configuration(self) -> Optional[int]: - """ - The current configuration the server is using., - """ - reg = self.register(JD_HID_ADAPTER_REG_CURRENT_CONFIGURATION) - values = reg.values() - return cast(Optional[int], values[0] if values else None) - - @current_configuration.setter - def current_configuration(self, value: int) -> None: - reg = self.register(JD_HID_ADAPTER_REG_CURRENT_CONFIGURATION) - reg.set_values(value) - - - def on_changed(self, handler: EventHandlerFn) -> UnsubscribeFn: - """ - Event that notifies clients that the server has swapped to a new configuration or changed key bindings. - """ - return self.on_event(JD_HID_ADAPTER_EV_CHANGED, handler) - - - def set_binding(self, configuration_number: int, binding_index: int, padding: int, device_id: int, service_class: int, trigger_value: int, trigger_context: int, service_index: int, selector: int, modifiers: undefined) -> None: - """ - Stores the given binding on the server. If a binding exists at this index, the new binding will replace it. - """ - self.send_cmd_packed(JD_HID_ADAPTER_CMD_SET_BINDING, configuration_number, binding_index, padding, device_id, service_class, trigger_value, trigger_context, service_index, selector, modifiers) - - def clear_binding(self, configuration_number: int, binding_index: int) -> None: - """ - Clears a specific binding stored on the device. - """ - self.send_cmd_packed(JD_HID_ADAPTER_CMD_CLEAR_BINDING, configuration_number, binding_index) - - def clear_configuration(self, configuration_number: int) -> None: - """ - Clears a specific configuration stored on the device. - """ - self.send_cmd_packed(JD_HID_ADAPTER_CMD_CLEAR_CONFIGURATION, configuration_number) - - def clear(self, ) -> None: - """ - Clears all configurations and bindings stored on the device. - """ - self.send_cmd_packed(JD_HID_ADAPTER_CMD_CLEAR, ) - diff --git a/jacdac/hid_adapter/constants.py b/jacdac/hid_adapter/constants.py deleted file mode 100644 index dde1177..0000000 --- a/jacdac/hid_adapter/constants.py +++ /dev/null @@ -1,20 +0,0 @@ -# Autogenerated constants for HID Adapter service -from jacdac.constants import * -from jacdac.system.constants import * -JD_SERVICE_CLASS_HID_ADAPTER = const(0x1e5758b5) -JD_HID_ADAPTER_REG_NUM_CONFIGURATIONS = const(0x80) -JD_HID_ADAPTER_REG_CURRENT_CONFIGURATION = const(0x81) -JD_HID_ADAPTER_CMD_GET_CONFIGURATION = const(0x80) -JD_HID_ADAPTER_CMD_SET_BINDING = const(0x82) -JD_HID_ADAPTER_CMD_CLEAR_BINDING = const(0x83) -JD_HID_ADAPTER_CMD_CLEAR_CONFIGURATION = const(0x84) -JD_HID_ADAPTER_CMD_CLEAR = const(0x85) -JD_HID_ADAPTER_EV_CHANGED = const(JD_EV_CHANGE) -JD_HID_ADAPTER_PACK_FORMATS = { - JD_HID_ADAPTER_REG_NUM_CONFIGURATIONS: "u8", - JD_HID_ADAPTER_REG_CURRENT_CONFIGURATION: "u8", - JD_HID_ADAPTER_CMD_GET_CONFIGURATION: "b[12] u8", - JD_HID_ADAPTER_CMD_SET_BINDING: "u8 u8 b[2] u64 u32 u32 u8 u8 u16 u16", - JD_HID_ADAPTER_CMD_CLEAR_BINDING: "u8 u8", - JD_HID_ADAPTER_CMD_CLEAR_CONFIGURATION: "u8" -} diff --git a/jacdac/relay/test.py b/jacdac/relay/test.py index e37df36..43629a7 100644 --- a/jacdac/relay/test.py +++ b/jacdac/relay/test.py @@ -3,25 +3,23 @@ from jacdac.devtools import create_dev_tools_bus from .client import RelayClient from time import sleep -bus = create_dev_tools_bus() +if __name__ == '__main__': + bus = create_dev_tools_bus() + def active(data: Any): + print("active") -def active(data: Any): - print("active") + def inactive(data: Any): + print("inactive") + rel = RelayClient(bus, "relay") + rel.on_active(active) + rel.on_inactive(inactive) -def inactive(data: Any): - print("inactive") - - -rel = RelayClient(bus, "relay") -rel.on_active(active) -rel.on_inactive(inactive) - -while True: - rel.closed = False - sleep(1) - print("open: ", rel.closed) - rel.closed = True - sleep(1) - print("closed: ", rel.closed) + while True: + rel.closed = False + sleep(1) + print("open: ", rel.closed) + rel.closed = True + sleep(1) + print("closed: ", rel.closed) diff --git a/test.py b/test.py index 03e84ff..a96b4cf 100644 --- a/test.py +++ b/test.py @@ -2,4 +2,5 @@ import sys from jacdac.bus import Bus from jacdac.transports.hf2 import HF2Transport -bus = Bus(HF2Transport(sys.argv[1])) +if __name__ == '__main__': + bus = Bus(HF2Transport(sys.argv[1]))