Documentation improvements, rewrite application development guides in Markdown

.gitignore

@@ -1,7 +1,8 @@
-venv/**
+venv/
 __pycache__
 pyrobusta.env
 build/
 runtime/
 runtime-test/
-tls/
+tls/
+tmp/

Makefile

@@ -3,11 +3,11 @@ DEVICE ?= u0
 
 SRC_DIR := src
 TEST_DIR := tests
-EXAMPLE_DIR := example/demo_app
+APP_DIR := example/demo_app
 BUILD_DIR := build
 DIST_DIR := dist
 TLS_DIR := tls
-ASSETS_DIR := assets
+DOCS_DIR := docs
 
 PKG := pyrobusta
 
@@ -30,7 +30,7 @@ DEVICE_NAME := # e.g. ESP32-C3, will be used for report generation
 PT_DIR := tests/system
 
 .PHONY: all
-all: clean toolchain static-checkers unit-test build test-unix deploy deploy-config tls-cert deploy-cert deploy-example
+all: clean toolchain static-checkers unit-test build test-unix deploy deploy-config tls-cert deploy-cert deploy-app
 
 # ================================================
 # Build
@@ -55,10 +55,7 @@ toolchain:
 .PHONY: build
 build: $(MPY_TARGETS) $(INIT_TARGETS)
 	@mkdir -p $(BUILD_DIR)
-	@if [ -d assets ]; then \
-		echo "Copying assets/ -> $(BUILD_DIR)"; \
-		cp -r assets $(BUILD_DIR)/${PKG}/; \
-	fi
+	$(MAKE) docs
 
 # Compile .py -> .mpy
 $(BUILD_DIR)/%.mpy: $(SRC_DIR)/%.py
@@ -126,44 +123,67 @@ redeploy: clean build clean-device deploy
 # Rules for release
 # ================================================
 
+# -----------------------------
+# Pre-process documentation
+# -----------------------------
+.PHONY: docs_preprocess
+docs_preprocess:
+	@find docs -type f -name "*.md" -exec \
+		sed -E -i.bak \
+		's/(PyRobusta[[:space:]]).+([[:space:]]Web Server)/\1$(PYROBUSTA_VERSION)\2/' {} \; \
+		&& find docs -name "*.bak" -delete
+
+
+# -----------------------------
+# Build documentation
+# -----------------------------
+.PHONY: docs
+docs: docs_preprocess
+	python3 scripts/generate_docs.py \
+		$(DOCS_DIR)/application_development \
+		$(BUILD_DIR)/$(PKG)/assets/www \
+		--css $(DOCS_DIR)/application_development/styles/style.css
+
+
 # -----------------------------
 # Prepare distribution
 # -----------------------------
 .PHONY: publish
 publish:
 	test -n "$(DIST_DIR)" && rm -rf "$(PWD)/$(DIST_DIR)"
 	mkdir -p "$(PWD)/$(DIST_DIR)"
-	@sed -E -i.bak 's/(PYROBUSTA_VERSION[[:space:]]*=[[:space:]]*)"[^"]*"/\1"$(PYROBUSTA_VERSION)"/' \
+
+	# Bump version in Python source
+	@sed -E -i.bak \
+		's/(PYROBUSTA_VERSION[[:space:]]*=[[:space:]]*)"[^"]*"/\1"$(PYROBUSTA_VERSION)"/' \
 		$(SRC_DIR)/pyrobusta/utils/config.py \
 		&& rm -f $(SRC_DIR)/pyrobusta/utils/config.py.bak
-	@sed -E -i.bak 's/(PyRobusta[[:space:]]).+([[:space:]]Web Server)/\1$(PYROBUSTA_VERSION)\2/' \
-		$(ASSETS_DIR)/www/*.html \
-		&& rm -f $(ASSETS_DIR)/www/*.html.bak
+
 	$(MAKE) clean
-	$(MAKE) build BUILD_DIR=$(DIST_DIR)
-	scripts/update_package.bash $(DIST_DIR) package.json $(PYROBUSTA_VERSION)
+	$(MAKE) build docs BUILD_DIR=$(DIST_DIR)
 
+	scripts/update_package.bash $(DIST_DIR) package.json $(PYROBUSTA_VERSION)
 
 # ================================================
 # Example apps
 # ================================================
 
 # -----------------------------
-# Prepare unix example runtime
+# Prepare UNIX example runtime
 # -----------------------------
-.PHONY: stage-example
-stage-example:
-	@echo "Preparing unix runtime in $(RUNTIME_DIR)"
+.PHONY: stage-app
+stage-app:
+	@echo "Preparing UNIX runtime in $(RUNTIME_DIR)"
 	@rm -rf $(RUNTIME_DIR)
 	@mkdir -p $(RUNTIME_DIR)/lib
 
 	@echo "Copying built package"
 	@cp -r build/pyrobusta $(RUNTIME_DIR)/lib
 	@cp -r build/pyrobusta/assets/www $(RUNTIME_DIR)/
 
-	@echo "Copying example app"
-	@cp $(EXAMPLE_DIR)/app.py $(RUNTIME_DIR)/
-	@cp $(EXAMPLE_DIR)/boot.py $(RUNTIME_DIR)/
+	@echo "Copying app"
+	@cp $(APP_DIR)/app.py $(RUNTIME_DIR)/
+	@cp $(APP_DIR)/boot.py $(RUNTIME_DIR)/
 
 	@echo "Copying TLS certificate"
 	@cp $(TLS_DIR)/cert.der $(RUNTIME_DIR)/
@@ -174,27 +194,27 @@ stage-example:
 	@echo "https_port=4443" >> $(RUNTIME_DIR)/pyrobusta.env
 
 # -----------------------------
-# Run example locally with unix micropython
+# Run app locally with UNIX MicroPython
 # -----------------------------
 .PHONY: run-unix
-run-unix: stage-example
-	@echo "Running example with unix micropython"
+run-unix: stage-app
+	@echo "Running app with UNIX MicroPython"
 	cd $(RUNTIME_DIR) && MICROPYPATH=":.frozen:lib" ../$(MICROPYTHON) app.py
 
 # -----------------------------
-# Deploy example app
+# Deploy application
 # -----------------------------
-.PHONY: deploy-example
-deploy-example:
+.PHONY: deploy-app
+deploy-app:
 	@echo "Uploading boot.py, app.py"
 	@mpremote $(DEVICE) soft-reset
-	mpremote $(DEVICE) cp $(EXAMPLE_DIR)/boot.py :boot.py
-	mpremote $(DEVICE) cp $(EXAMPLE_DIR)/app.py :app.py
+	mpremote $(DEVICE) cp $(APP_DIR)/boot.py :boot.py
+	mpremote $(DEVICE) cp $(APP_DIR)/app.py :app.py
 
 	@echo "Uploading pyrobusta.env"
 	@if [ -f pyrobusta.env ]; then mpremote $(DEVICE) cp pyrobusta.env :pyrobusta.env; fi
 	@mpremote $(DEVICE) reset
-	@echo "\e[32m$(EXAMPLE_DIR) example is successfully deployed, \n"\
+	@echo "\e[32m$(APP_DIR) app is successfully deployed, \n"\
 	"run 'make DEVICE=$(DEVICE) run-device' to restart the device and check the output.\e[0m"
 
 # -----------------------------
@@ -259,7 +279,7 @@ stage-test:
 	@cp tests/functional/*.py $(TEST_RUNTIME)/
 
 # -----------------------------
-# Run functional tests on unix port
+# Run functional tests on UNIX port
 # -----------------------------
 .PHONY: test-unix
 test-unix: TLS_DIR=$(TEST_RUNTIME)

README.md

@@ -102,13 +102,17 @@ async def main():
 asyncio.run(main())
 ```
 
+Check the [Application Development](./docs/application_development/index.md) guide for
+more details on supported features and practical examples.
+
+
 # Configuration and Optimization
 
 To fine-tune heap usage and optimize performance, see:
-- [dimensioning guide](./docs/dimensioning/http_dimensioning.md)
-- [configuration settings](./docs/configuration.md)
+- [Dimensioning](./docs/dimensioning/http_dimensioning.md)
+- [Configuration Settings](./docs/application_development/configuration.md)
 
 # Development
 
-Check the provided development guide to create and deploy custom builds
-to your device: [development guide](./docs/development.md)
+Check the provided [Development](./docs/development.md) guide to create and deploy custom builds
+to your device, as well as running tests and static code checkers.