From 27e35527ff2201045102eb9f4cc73776aa002b0a Mon Sep 17 00:00:00 2001 From: Daniel Thompson Date: Sat, 22 Feb 2020 21:17:30 +0000 Subject: [PATCH] docs: Use sphinx to gather together all the wasp docs --- .gitignore | 1 + Makefile | 8 +++++-- README.md | 3 +++ TODO.md | 22 ++++++++++--------- docs/Makefile | 20 +++++++++++++++++ docs/README.md | 1 + docs/TODO.md | 1 + docs/conf.py | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 23 ++++++++++++++++++++ docs/res | 1 + docs/wasp.rst | 30 +++++++++++++++++++++++++ 11 files changed, 157 insertions(+), 12 deletions(-) create mode 100644 docs/Makefile create mode 120000 docs/README.md create mode 120000 docs/TODO.md create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 120000 docs/res create mode 100644 docs/wasp.rst diff --git a/.gitignore b/.gitignore index 0f37717..16efb0b 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,5 @@ *.zip .*.swp __pycache__ +docs/build attic/ diff --git a/Makefile b/Makefile index c2ff1b5..b038685 100644 --- a/Makefile +++ b/Makefile @@ -54,10 +54,14 @@ debug: -ex "attach 1" \ -ex "load" +docs: + $(MAKE) -C docs html + + sim: PYTHONDONTWRITEBYTECODE=1 \ PYTHONPATH=$(PWD)/wasp/boards/simulator:$(PWD)/wasp \ - python3 -i wasp/boot.py + python3 -i wasp/main.py -.PHONY: bootloader micropython +.PHONY: bootloader docs micropython diff --git a/README.md b/README.md index 83fceec..d7d9af4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,9 @@ Watch Application System in Python ================================== +Introduction +------------ + Currently in its infancy wasp-os provides nothing more than a simple digital clock application for [PineTime](https://www.pine64.org/pinetime/) together with access to the MicroPython REPL for interactive testing and diff --git a/TODO.md b/TODO.md index 7292794..d09106e 100644 --- a/TODO.md +++ b/TODO.md @@ -1,10 +1,12 @@ -# M1: Dumb watch feature parity +# Roadmap + +## M1: Dumb watch feature parity The focus for M1 is to get WASP both to meet feature parity with a dumb watch and to have a bootloader and watchdog strategy that is robust enough to allow a PineTime case to be confidently glued shut. -## Bootloader +### Bootloader * [X] Basic board ports (PineTime, DS-D6, 96Boards Nitrogen) * [X] OTA application update @@ -12,14 +14,14 @@ to allow a PineTime case to be confidently glued shut. * [X] Splash screen * [X] Ignore start button for first few seconds -## MicroPython +### MicroPython * [X] Basic board ports (PineTime, DS-D6, 96Boards Nitrogen) * [X] Long press reset (conditional feeding of the watchdog) - [X] Feed dog from REPL polling loop - [X] Feed dog from a tick interrupt -## WASP +### WASP * [X] Display driver - [X] Display initialization @@ -33,7 +35,7 @@ to allow a PineTime case to be confidently glued shut. * [X] Basic (WFI) power saving * [X] Implement simple RTC for nrf52 -# M2: Great developer experience +## M2: Great developer experience The focus for M2 is to make development faster and easier by providing a file system and file transfer code. This allows much faster @@ -42,21 +44,21 @@ Additionally support for multiple event-driven applications will be added during M2 to further help developers by providing example applications. -## Bootloader +### Bootloader * [ ] OTA bootloader update * [ ] Stay in bootloader after battery run down * [ ] Implement power off support (no splash screen) * [ ] RTC time measurement whilst in bootloader -## MicroPython +### MicroPython * [X] SPI FLASH driver * [X] Enable LittleFS on SPI FLASH (at boot) * [X] BLE file transfer * [ ] Full power saving -## WASP +### WASP * [X] Add dd/mm/yyyy support to RTC * [ ] Button driver (interrupt based) @@ -70,12 +72,12 @@ applications. - [ ] Document bootloader protocols - [ ] Write full docstring documentation for all WASP components -# M3: Smartwatch +## M3: Smartwatch At M3 we start to build out full fitness tracking and notification functionality. -## WASP +### WASP * [ ] Enable heart rate sensor - [ ] HRS3300 driver diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..ed88099 --- /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/README.md b/docs/README.md new file mode 120000 index 0000000..32d46ee --- /dev/null +++ b/docs/README.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file diff --git a/docs/TODO.md b/docs/TODO.md new file mode 120000 index 0000000..15d039a --- /dev/null +++ b/docs/TODO.md @@ -0,0 +1 @@ +../TODO.md \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..957072a --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,59 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- 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('../wasp')) +sys.path.insert(0, os.path.abspath('../wasp/boards/simulator')) + + +# -- Project information ----------------------------------------------------- + +project = 'WASP-OS' +copyright = '2020, Daniel Thompson' +author = 'Daniel Thompson' + + +# -- 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 = [ + 'sphinx.ext.autodoc', + 'recommonmark', +] + +# 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'] + +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', +} + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# 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'] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..84c9765 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,23 @@ +.. WASP-OS documentation master file, created by + sphinx-quickstart on Sat Feb 22 20:30:29 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to WASP-OS's documentation! +=================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + README + wasp + TODO + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/res b/docs/res new file mode 120000 index 0000000..dbbfe3c --- /dev/null +++ b/docs/res @@ -0,0 +1 @@ +../res/ \ No newline at end of file diff --git a/docs/wasp.rst b/docs/wasp.rst new file mode 100644 index 0000000..4c0c0ff --- /dev/null +++ b/docs/wasp.rst @@ -0,0 +1,30 @@ +WASP Internals +============== + +System management +----------------- + +.. automodule:: manager + :members: + :undoc-members: + +Applications +------------ + +.. automodule:: clock + :members: + :undoc-members: + +Device drivers +-------------- + +.. automodule:: drivers.st7789 + :members: + :undoc-members: + +Libraries +--------- + +.. automodule:: draw565 + :members: + :undoc-members: