diff --git a/firmware/asdf/Pipfile b/firmware/asdf/Pipfile new file mode 100644 index 0000000..7ce1829 --- /dev/null +++ b/firmware/asdf/Pipfile @@ -0,0 +1,20 @@ +[[source]] +name = "pypi" +url = "https://pypi.org/simple" +verify_ssl = true + +[dev-packages] +black = "*" +flake8 = "*" +pylint = "*" +mypy = "*" + +[packages] +sphinx = "*" +sphinx-autodoc-typehints = "*" +sphinx-rtd-theme = "*" +toml = "*" +intelhex = "*" + +[requires] +python_version = "3" diff --git a/firmware/asdf/docs/Makefile b/firmware/asdf/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/firmware/asdf/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 = source +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/firmware/asdf/docs/make.bat b/firmware/asdf/docs/make.bat new file mode 100644 index 0000000..747ffb7 --- /dev/null +++ b/firmware/asdf/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=source +set BUILDDIR=build + +%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 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/firmware/asdf/docs/source/_templates/hexfile_link.in b/firmware/asdf/docs/source/_templates/hexfile_link.in new file mode 100644 index 0000000..bc266af --- /dev/null +++ b/firmware/asdf/docs/source/_templates/hexfile_link.in @@ -0,0 +1,7 @@ +.. _@ARCH@ Rev @CMAKE_PROJECT_VERSION@: + +ASDF Rev @CMAKE_PROJECT_VERSION@ hex file (@ARCH@) +---------------------------------------------------------------------------------- + +:ASDF Firmware @CMAKE_PROJECT_VERSION@-@ARCH@: + :download:`@hex_file@` diff --git a/firmware/asdf/docs/source/_templates/index.rst.in b/firmware/asdf/docs/source/_templates/index.rst.in new file mode 100644 index 0000000..03849d2 --- /dev/null +++ b/firmware/asdf/docs/source/_templates/index.rst.in @@ -0,0 +1,8 @@ +Unified Retro Keyboard firmware (ASDF) rev @CMAKE_PROJECT_VERSION@ +======================================================================= + +.. toctree:: + :caption: Downloads + :glob: + + toc_* diff --git a/firmware/asdf/docs/source/conf.py b/firmware/asdf/docs/source/conf.py new file mode 100644 index 0000000..8ee8669 --- /dev/null +++ b/firmware/asdf/docs/source/conf.py @@ -0,0 +1,63 @@ +# 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: +# 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 +import re +import toml + +# -- Project information ----------------------------------------------------- + +project = "ASDF - Unified Retro Keyboard Firmware" +copyright = "2022 Osiweb.org" +author = "David F" + +# -- 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.napoleon", + "sphinx.ext.autodoc", # Core library for html generation from docstrings + "sphinx_autodoc_typehints", + "sphinx.ext.viewcode", + "sphinx.ext.autosectionlabel", + "sphinx.ext.autosummary", # Create neat summary tables +] +autosummary_generate = True # Turn on sphinx.ext.autosummary + +# 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 = [] + + +# -- 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 = "sphinx_rtd_theme" + +# 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" +] # Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html diff --git a/firmware/asdf/make-build-dirs.sh b/firmware/asdf/make-build-dirs.sh deleted file mode 100755 index e62bd8c..0000000 --- a/firmware/asdf/make-build-dirs.sh +++ /dev/null @@ -1,118 +0,0 @@ -#!/opt/local/bin/bash - - -CMAKE_TARGETS="" -VALID_TARGETS="" - -add_valid_target() { - VALID_TARGETS+=" $1 " -} - -add_valid_target test -add_valid_target atmega328p -add_valid_target atmega2560 - -build_arch() { - - for target_arch in "$@" - do - if [[ ! -d "build-$target_arch" ]] - then - echo -ne "\nCreating directory $target_arch..." - mkdir "build-$target_arch" && echo "[success]" - else - echo "Directory \"$target_arch\" exists." - fi - - if [[ -d "build-$target_arch" ]] - then - echo -e "\nRunning CMake in directory $target_arch..." - (cd "build-$target_arch" && cmake -DARCH=$target_arch ..) - echo - fi - done -} - -main() { - parse $@ - - echo "Valid: $VALID_TARGETS" - echo "Selected: $CMAKE_TARGETS" - - run -} - -run() { - echo "$CMAKE_TARGETS" - - build_arch $CMAKE_TARGETS -} - - -syntax() { - echo "Usage:" - echo " $0 -t target [-t target] ..." - echo " $0 -a" - echo " $0 -h" - echo "" - echo "Options:" - echo " -t add an architecture directory" - echo " -h Display this help message" - echo " -a Add all valid architecture directories" - echo "" - echo "Valid targets: $VALID_TARGETS" -} - -parse() { - local SYNTAX="" - local ALL="" - - while getopts "t:ah" optname - do - case "$optname" in - h) - SYNTAX="yes" - ;; - a) - ALL="yes" - ;; - t) - # Test that target is valid and not already specified - if [[ " $VALID_TARGETS " == *" $OPTARG "* ]] - then - if [[ " $CMAKE_TARGETS " != *" $OPTARG "* ]] - then - CMAKE_TARGETS+=" $OPTARG " - fi - else - SYNTAX="yes" - fi - ;; - esac - done - - if [[ "$SYNTAX" == "yes" ]]; then - syntax && die - fi - - if [[ "$ALL" == "yes" ]] - then - CMAKE_TARGETS="$VALID_TARGETS" - fi - - if [[ -z "$CMAKE_TARGETS" ]] - then - die "No targets!" - fi -} - -die() { - builtin echo $@ - exit 1 -} - -main $@ - -exit 0 - - diff --git a/firmware/asdf/make-targets.sh b/firmware/asdf/make-targets.sh new file mode 100755 index 0000000..4dd7835 --- /dev/null +++ b/firmware/asdf/make-targets.sh @@ -0,0 +1,230 @@ +#!/bin/bash + +GENERATOR="Unix Makefiles" +NUM_VALID_TARGETS=0 +BUILD_TYPE=RELEASE +INSTALL_DIR="dist" +MAKE_TARGETS="all" +DOC_DIR=docs +LINKS_DIR="$DOC_DIR/source" + +add_valid_target() { + VALID_TARGETS[$NUM_VALID_TARGETS]=$1 + HW_SIGS[$NUM_VALID_TARGETS]=$2 + ((NUM_VALID_TARGETS++)) +} + +add_valid_target test +add_valid_target atmega328p +add_valid_target atmega2560 + + +check_valid_target() { + result="false" + + for (( i = 0; i < NUM_VALID_TARGETS; i++ )) + do + if [[ ${VALID_TARGETS[$i]} == $1 ]] + then + result=$i + fi + done + echo $result +} + + +do_pipenv_clean() { + echo removing old python virtual environment... + pipenv --rm +} + + +do_pipenv_install() { + echo installing python virtual environment... + pipenv install +} + +clean_arch() { + target_arch="$1" + echo "Removing pre-existing build directory: $target_arch..." + rm -rf "build-$target_arch" + echo "Removing any build artifacts" + rm -f $INSTALL_DIR/*"$1"* + echo "Removing any download links" + rm -f $LINKS_DIR/*$1* +} + +build_arch() { + local target_arch="$1" + local hardware_sig="$2" + + if [[ ! -d "build-$target_arch" ]] + then + mkdir "build-$target_arch" + fi + + if [[ -d "build-$target_arch" ]] + then + (cd "build-$target_arch" \ + && cmake -G "$GENERATOR" -DCMAKE_INSTALL_PREFIX=".." -DARCH="$target_arch" \ + -DCMAKE_BUILD_TYPE="$BUILD_TYPE" ..) + fi +} + +deploy_arch() { + local target_arch="$1" + + if [[ -d "build-$target_arch" ]] + then + (cd "build-$target_arch" \ + && make install) + fi +} + +clean_all() { + echo "- Removing install dir \"$INSTALL_DIR\"..." + rm -rvf "$INSTALL_DIR" + echo "- Removing download links..." + rm -vf $DOC_DIR/source/toc_* + echo "- Removing versioned index file" + rm -vf "$DOC_DIR/source/index.rst" +} + +syntax() { + echo "Usage:" + echo " $0 -t target [-t target] ..." + echo " $0 -a" + echo " $0 -h" + echo "" + echo "Options:" + echo " -h. Display this help message" + echo " -x Before creating a build directgory or virtual env, remove" + echo " any pre-existing version" + echo " -t add an architecture directory" + echo " -a Add all valid architecture directories" + echo " -i Build each specified target and install to dist directory" + echo " -p Install pipenv virtual environment for python scripts" + echo " -c Clean all artifacts" + echo " -s Copy dist files to sphinx directory" + echo "Valid targets: ${VALID_TARGETS[*]}" +} + +parse() { + local SYNTAX="" + local ALL="" + local i + local valid_index + + NUM_CMAKE_TARGETS=0 + CLEAN_BEFORE_BUILD="" + DO_PIPENV_INSTALL="" + DEPLOY="" + CLEAN_ALL="" + COPY_DIST_TO_DOCS="" + + while getopts "t:ahipxcs" optname + do + case "$optname" in + h) + SYNTAX="yes" + ;; + a) + ALL="yes" + ;; + t) + # Test that target is valid + valid_index=$(check_valid_target $OPTARG) + if [[ $valid_index != "false" ]] + then + CMAKE_TARGETS[$NUM_CMAKE_TARGETS]=$valid_index + ((NUM_CMAKE_TARGETS++)) + else + echo Unknown target \"$OPTARG\" + SYNTAX="yes" + fi + ;; + p) + DO_PIPENV_INSTALL="yes" + ;; + x) + CLEAN_BEFORE_BUILD="yes" + ;; + i) DEPLOY="yes" + ;; + s) COPY_DIST_TO_DOCS="yes" + ;; + c) CLEAN_ALL="yes" + + esac + done + + if [[ "$SYNTAX" == "yes" ]]; then + syntax && die + fi + + if [[ "$ALL" == "yes" ]] + then + for (( i=0; i