mirror/Meshtastic-Android
1
0
Fork 0
mirror of https://github.com/meshtastic/Meshtastic-Android.git synced 2026-05-12 08:42:01 -04:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
Meshtastic-Android/specs/003-app-docs-markdown/tasks.md

17 KiB
Raw Permalink Blame History

description
description
Task list for feature: App Documentation (Android/KMP)

Tasks: App Documentation (Android/KMP)

Input: Design documents from specs/003-app-docs-markdown/
Prerequisites: spec.md, plan.md, research.md, data-model.md, contracts/, quickstart.md
Status: Not Started

Format: [ID] [P?] [Story] Description

  • [P]: Can be worked in parallel if dependencies are satisfied
  • [Story]: US1..US5 map to the user stories in spec.md
  • Every task names the primary file paths to touch

Phase 0: Design Standards Gate (Blocking)

Purpose: Review Meshtastic design standards before shipping any new UI for docs or the Chirpy assistant.

  • T000 [UI-GATE] Review .skills/design-standards/SKILL.md and upstream Meshtastic design standards; record constraints for feature/docs/src/commonMain/kotlin/org/meshtastic/feature/docs/ui/DocsBrowserScreen.kt, ChirpyAssistantSheet.kt, and screenshot styling.
  • T001 [UI-GATE] Confirm icon choices in core/ui/src/commonMain/kotlin/org/meshtastic/core/ui/icon/ for help/search/info/security states and choose MeshtasticIcons equivalents for docs UI and reference tables.

Checkpoint: Design constraints are documented and ready to guide implementation.

Phase 1: Documentation Content

Purpose: Author the docs corpus that both the website and in-app browser will consume.

User Guide pages

  • T010 [P] [US1] Create docs/user/onboarding.md covering first launch, intro flow, permissions, and initial setup using content from feature/intro/src/androidMain/kotlin/org/meshtastic/feature/intro/WelcomeScreen.kt, LocationScreen.kt, and NotificationsScreen.kt.
  • T011 [P] [US1] Create docs/user/connections.md covering Bluetooth, USB, and TCP connection flows using feature/intro/.../BluetoothScreen.kt and feature/connections/** as authoritative sources.
  • T012 [P] [US1] Create docs/user/messages-and-channels.md covering conversations, channel security, direct messages, and message state using feature/messaging/src/commonMain/kotlin/org/meshtastic/feature/messaging/Message.kt and component/MessageScreenComponents.kt.
  • T013 [P] [US1] Create docs/user/nodes.md covering node list status, roles, badges, and quick actions using feature/node/src/commonMain/kotlin/org/meshtastic/feature/node/list/NodeListScreen.kt.
  • T014 [P] [US1] Create docs/user/node-metrics.md covering node detail, device metrics, environment metrics, signal, power, traceroute, and logs using feature/node/src/commonMain/kotlin/org/meshtastic/feature/node/detail/NodeDetailScreens.kt and metrics/*.
  • T015 [P] [US1] Create docs/user/map-and-waypoints.md covering maps, waypoints, and map-specific actions using feature/map/src/androidMain/kotlin/org/meshtastic/feature/map/MapScreen.kt.
  • T016 [P] [US1] Create docs/user/settings-radio-user.md covering radio, LoRa, display, and user settings using feature/settings/src/commonMain/kotlin/org/meshtastic/feature/settings/DeviceConfigurationScreen.kt.
  • T017 [P] [US1] Create docs/user/settings-module-admin.md covering module, administration, and advanced settings using feature/settings/src/commonMain/kotlin/org/meshtastic/feature/settings/ModuleConfigurationScreen.kt and AdministrationScreen.kt.
  • T018 [P] [US1] Create docs/user/telemetry-and-sensors.md covering telemetry surfaces and sensor interpretation using feature/node/src/commonMain/kotlin/org/meshtastic/feature/node/metrics/EnvironmentMetrics.kt, PowerMetrics.kt, and related metric screens.
  • T019 [P] [US1] Create docs/user/tak.md covering TAK integration and setup using feature/settings/src/commonMain/kotlin/org/meshtastic/feature/settings/radio/component/TAKConfigItemList.kt and related settings screens.
  • T020 [P] [US1] Create docs/user/mqtt.md covering MQTT setup and usage using feature/settings/src/commonMain/kotlin/org/meshtastic/feature/settings/radio/component/MQTTConfigItemList.kt and messaging references.
  • T021 [P] [US1] Create docs/user/discovery.md covering local mesh discovery and node exploration based on current discovery-related UI/state and app navigation flows. Note: Feature 001 (Local Mesh Discovery) is Not Started — author this page as a concept/goals overview initially and revise with screenshots and detailed UI guidance once 001 reaches Phase 5+ UI milestones.
  • T022 [P] [US1] Create docs/user/firmware.md covering update flows, warnings, and recovery using feature/firmware/src/commonMain/kotlin/org/meshtastic/feature/firmware/FirmwareUpdateScreen.kt.
  • T023 [P] [US1] Create docs/user/desktop.md covering Desktop host usage, transport differences, and parity notes using desktop/src/main/kotlin/org/meshtastic/desktop/ and shared navigation patterns.

Developer Guide pages

  • T024 [P] [US4] Create docs/developer/architecture.md describing layer boundaries (app, desktop, feature/*, core/*) and shared KMP responsibilities.
  • T025 [P] [US4] Create docs/developer/codebase.md documenting repository layout, namespacing, and build-logic conventions.
  • T026 [P] [US4] Create docs/developer/adding-a-feature-module.md documenting meshtastic.kmp.feature, source sets, DI, resources, and testing expectations.
  • T027 [P] [US4] Create docs/developer/navigation-and-deep-links.md documenting Routes.kt, DeepLinkRouter.kt, and Navigation 3 graph registration patterns.
  • T028 [P] [US4] Create docs/developer/transport.md documenting BLE, TCP, Serial/USB, and host-specific abstractions.
  • T029 [P] [US4] Create docs/developer/persistence.md documenting Room KMP, DataStore/core:prefs, and where docs intentionally do not use persistence.
  • T030 [P] [US4] Create docs/developer/testing.md documenting KMP test strategy, host tests, and planned screenshot automation.
  • T031 [P] [US4] Create docs/developer/contributing.md documenting branch naming, verification, and PR hygiene.

Content-supporting assets

  • T032 [P] [US1] Create or inventory docs/assets/screenshots/ references and map each page to required PNG or SVG assets.
  • T033 [P] [US1] Extract onboarding tips, warnings, and disclaimers from feature/intro/**, feature/firmware/**, and relevant feature UIs into highlighted callout sections inside the authored markdown.
  • T034 [US1] Review all markdown for reference-table compliance where 2+ icon/state captures appear together.

Checkpoint: Complete markdown corpus exists with planned screenshots and callouts.

Phase 2: Jekyll Site Setup

Purpose: Make the authored markdown browsable on the web with versioning.

  • T040 [P] [US1] Create docs/_config.yml with just-the-docs, sidebar search, and the required collection/navigation settings.
  • T041 [P] [US1] Create docs/index.md redirect behavior for /latest/ and beta handling.
  • T042 [P] [US1] Create docs/_data/versions.yml with an initial beta entry and stable release entry schema.
  • T043 [P] [US1] Create any shared include/layout files needed for version selector, beta banner, and consistent screenshot styling.
  • T044 [US1] Validate local Jekyll build output from the authored markdown and confirm the navigation hierarchy matches the spec.

Checkpoint: Local website build is navigable and version-ready.

Phase 3: Build Pipeline (Markdown → HTML, Index, Bundle)

Purpose: Implement Gradle-native docs generation suitable for KMP.

  • T050 [P] [US1] Create feature/docs/build.gradle.kts using meshtastic.kmp.feature and dependencies for core:common, core:navigation, core:resources, core:ui, core:di, and existing markdown renderer libraries.
  • T051 [P] [US1] Add :feature:docs to settings.gradle.kts.
  • T052 [P] [US1] Add docs-generation support in build-logic/convention/src/main/kotlin/org/meshtastic/buildlogic/DocsTasks.kt (or equivalent) with lazy task registration.
  • T053 [P] [US1] Implement frontmatter parsing, nav-order extraction, and markdown normalization in build logic or feature/docs build task code.
  • T054 [P] [US1] Implement HTML rendering via flexmark-java (or commonmark-java fallback) in the docs generation task.
  • T055 [P] [US1] Implement callout and banner post-processing, shared CSS injection, and data-page emission for generated HTML.
  • T056 [P] [US1] Generate index.json matching specs/003-app-docs-markdown/contracts/keyword-index-schema.json.
  • T057 [P] [US1] Wire generated output into feature/docs/build/generated/docs/common/ as a Gradle resource source directory.
  • T058 [P] [US1] Add Android asset mirroring if required for WebView file loading under feature/docs/build/generated/docs/androidAssets/.
  • T059 [P] [US1] Enforce bundle-size warnings/failures and missing-asset validation in validateDocsBundle.
  • T060 [US1] Add aggregate root tasks (generateDocsBundle, validateDocsBundle, publishDocsSite) and document their usage.

Checkpoint: Gradle can generate the docs bundle and website artifact from markdown.

Phase 4: In-App Doc Browser

Purpose: Ship the offline docs browser inside Settings.

  • T070 [P] [US2] Create feature/docs/src/commonMain/kotlin/org/meshtastic/feature/docs/model/DocModels.kt implementing the entities from data-model.md.
  • T071 [P] [US2] Create feature/docs/src/commonMain/kotlin/org/meshtastic/feature/docs/data/DocBundleLoader.kt to load packaged docs metadata and page content.
  • T072 [P] [US2] Create feature/docs/src/commonMain/kotlin/org/meshtastic/feature/docs/ui/DocsBrowserScreen.kt with grouped TOC, search entry point, and loading/empty states.
  • T073 [P] [US2] Create feature/docs/src/commonMain/kotlin/org/meshtastic/feature/docs/ui/DocsPageRouteScreen.kt to route page IDs to renderer surfaces.
  • T074 [P] [US2] Create Android renderer feature/docs/src/androidMain/kotlin/org/meshtastic/feature/docs/ui/DocHtmlView.android.kt using AndroidView + WebView.
  • T075 [P] [US2] Create Desktop/iOS page renderers in src/jvmMain and src/iosMain using Compose markdown or embedded browser abstraction.
  • T076 [P] [US2] Create feature/docs/src/commonMain/kotlin/org/meshtastic/feature/docs/navigation/DocsNavigation.kt with typed navigation entries.
  • T077 [P] [US2] Add SettingsRoute.HelpDocs and SettingsRoute.HelpDocPage to core/navigation/src/commonMain/kotlin/org/meshtastic/core/navigation/Routes.kt.
  • T078 [P] [US2] Update core/navigation/src/commonMain/kotlin/org/meshtastic/core/navigation/DeepLinkRouter.kt for help-docs (canonical) / helpDocs (compat alias) routing.
  • T079 [P] [US2] Update feature/settings/src/commonMain/kotlin/org/meshtastic/feature/settings/navigation/SettingsNavigation.kt to add the Help & Documentation row and register docs destinations.
  • T080 [P] [US2] Create feature/docs/src/commonMain/kotlin/org/meshtastic/feature/docs/di/FeatureDocsModule.kt.
  • T081 [P] [US2] Include FeatureDocsModule in app/src/main/kotlin/org/meshtastic/app/di/AppKoinModule.kt and desktop/src/main/kotlin/org/meshtastic/desktop/di/DesktopKoinModule.kt.
  • T082 [US2] Add shared/unit tests for bundle loading, page ordering, and route serialization under feature/docs/src/commonTest/kotlin/org/meshtastic/feature/docs/.

Checkpoint: Help & Documentation opens inside Settings and reads bundled content offline.

Phase 5: Search / Index / Discoverability

Purpose: Make the docs corpus searchable on all targets.

  • T090 [P] [US2] Create feature/docs/src/commonMain/kotlin/org/meshtastic/feature/docs/data/KeywordSearchEngine.kt using KeywordIndexEntry.
  • T091 [P] [US2] Add alias normalization and title-first ranking logic.
  • T092 [P] [US2] Create feature/docs/src/commonMain/kotlin/org/meshtastic/feature/docs/ui/DocsSearchBar.kt and wire it into DocsBrowserScreen.kt.
  • T093 [P] [US2] Add section-aware search results and page suggestions for missing page/deep-link cases.
  • T094 [P] [US2] Add tests for ranking, aliases, and tie-breaking in KeywordSearchEngineTest.kt.
  • T095 [US2] Ensure keyword search is the user-visible fallback on unsupported AI targets.

Checkpoint: Search works without AI on every target.

Phase 6: AI Assistant (Gemini Nano)

Purpose: Add an Android-only on-device assistant without breaking KMP or fdroid.

  • T100 [P] [US3] Create shared AI contracts in feature/docs/src/commonMain/kotlin/org/meshtastic/feature/docs/ai/AIDocAssistant.kt and result/state models.
  • T101 [P] [US3] Create feature/docs/src/commonMain/kotlin/org/meshtastic/feature/docs/ui/ChirpyAssistantSheet.kt with chat UI, pinned input, session history, and source-page chips.
  • T102 [P] [US3] Add keyword-retrieval + token-budget helper logic in shared code.
  • T103 [P] [US3] Implement Google-flavor Android binding under app/src/google/kotlin/org/meshtastic/app/docs/GoogleDocsAiModule.kt (or equivalent) to call Gemini Nano via Google AI Edge SDK.
  • T104 [P] [US3] Bind a no-op or keyword-only fallback implementation in app/src/fdroid/kotlin/org/meshtastic/app/di/FlavorModule.kt.
  • T105 [P] [US3] Bind a Desktop fallback implementation from desktop/src/main/kotlin/org/meshtastic/desktop/di/DesktopKoinModule.kt.
  • T105b [P] [US3] Bind an iOS fallback implementation (keyword-search-only, sharing the Desktop fallback pattern) in the iOS Koin module or via a shared non-Android default binding.
  • T106 [P] [US3] Add runtime capability checks for Android API level, flavor, model availability, and busy/quota states.
  • T107 [P] [US3] Surface assistant fallback states cleanly in the shared UI and hide the input entirely when unsupported.
  • T108 [P] [US3] Add tests covering token budget trimming, unsupported platform behavior, and fallback search suggestions.
  • T109 [US3] Verify the Chirpy vector asset is bundled and rendered correctly across targets.

Checkpoint: Supported Android Google builds get Gemini Nano; all other targets fall back gracefully.

Phase 7: CI Automation and GitHub Pages

Purpose: Keep docs current and deployable.

  • T120 [P] [US5] Create .github/workflows/docs-deploy.yml using ubuntu-24.04, JDK 21, Gradle setup, docs-generation tasks, and Pages deploy steps.
  • T121 [P] [US5] Create .github/workflows/docs-release.yml for v*.*.* tags, version manifest updates, and /latest/ redirect refresh.
  • T122 [P] [US5] Create or wire recordDocsScreenshots to the chosen screenshot framework (Roborazzi preferred, Paparazzi acceptable).
  • T123 [P] [US5] Add screenshot asset diff detection and automated PR creation logic for changed PNGs.
  • T124 [P] [US5] Add schema validation against specs/003-app-docs-markdown/contracts/keyword-index-schema.json during CI.
  • T125 [P] [US5] Add bundle-size validation and missing-asset validation to CI as blocking steps.
  • T126 [P] [US5] Update workflow permissions and Pages artifact publishing configuration.
  • T127 [US5] Dry-run the workflows locally as far as practical and verify contract alignment.

Checkpoint: Docs build, validate, and deploy automatically in CI.

Phase 8: Polish, Accessibility, and Edge Cases

Purpose: Final quality pass before implementation is considered complete.

  • T130 [P] [US2] Add accessibility labels, headings, and focus order checks to docs browser and Chirpy UI.
  • T131 [P] [US2] Validate dark-mode rendering for generated HTML, screenshots, and icon reference tables.
  • T132 [P] [US2] Handle missing-page and stale-deep-link fallbacks in the docs browser UI.
  • T133 [P] [US3] Add explicit user messaging for Gemini busy/quota/model-not-installed states.
  • T134 [P] [US1] Review all pages for plain-language voice, no internal jargon leaks, and consistency with current UI strings.
  • T135 [P] [US4] Review developer docs for correctness against actual modules, routes, and DI setup.
  • T136 [P] [US5] Validate Lighthouse accessibility on the generated site and record results.
  • T137 [P] [US5] Add README updates for Help & Documentation and the deep-link contract.
  • T138 [US1] Run final verification: ./gradlew spotlessCheck detekt kmpSmokeCompile test allTests generateDocsBundle validateDocsBundle publishDocsSite.

Checkpoint: Feature is accessible, correct, and release-ready.

Dependency Notes

  • Phase 0 blocks all UI work.
  • Phase 1 (content) and Phase 2 (site scaffolding) can overlap.
  • Phase 3 must finish before Phase 4 can load generated bundles reliably.
  • Phase 5 depends on Phase 3 metadata/index generation and Phase 4 browser UI.
  • Phase 6 depends on Phase 5 because AI retrieval uses the keyword index and search engine.
  • Phase 7 depends on Phases 2 and 3.
  • Phase 8 depends on all preceding phases.

Recommended Delivery Order

  1. Ship US1 first (web docs + pipeline).
  2. Add US2 (in-app browser + deep links).
  3. Add US3 (Gemini Nano + fallbacks).
  4. Finish US4 polishing and architecture docs.
  5. Finish US5 automation and screenshot bot flow.
Reference in New Issue View Git Blame Copy Permalink