omar/MosisService

Fork 0

Files

omigamedev 5cfee2aa66 add developer portal planning documentation (M01-M12)

2026-01-18 17:20:51 +01:00

12 KiB

Raw Blame History

Milestone 12: Documentation Site

Status: Planning Goal: Comprehensive documentation for Mosis app developers.

Overview

The documentation site is the primary resource for developers learning to build Mosis apps. Must be clear, searchable, and up-to-date.

Information Architecture

docs.mosis.dev/
├── Getting Started
│   ├── Introduction
│   ├── Quick Start (5 min)
│   ├── Your First App
│   └── Project Structure
├── Guides
│   ├── UI Design
│   │   ├── RML Basics
│   │   ├── Styling with RCSS
│   │   ├── Layouts
│   │   └── Components
│   ├── Lua Scripting
│   │   ├── Basics
│   │   ├── Event Handling
│   │   ├── State Management
│   │   └── Async Operations
│   ├── Data & Storage
│   │   ├── Local Storage
│   │   ├── SQLite Database
│   │   └── Files
│   ├── Networking
│   │   ├── HTTP Requests
│   │   └── WebSockets
│   ├── Hardware
│   │   ├── Camera
│   │   ├── Microphone
│   │   ├── Location
│   │   └── Sensors
│   ├── Permissions
│   │   ├── Permission Model
│   │   ├── Requesting Permissions
│   │   └── User Gestures
│   └── Publishing
│       ├── Preparing for Release
│       ├── App Signing
│       └── Store Guidelines
├── API Reference
│   ├── Lua APIs
│   │   ├── mosis.storage
│   │   ├── mosis.db
│   │   ├── mosis.http
│   │   ├── mosis.ws
│   │   ├── mosis.camera
│   │   ├── mosis.microphone
│   │   ├── mosis.location
│   │   ├── mosis.sensors
│   │   └── ...
│   ├── RML Elements
│   ├── RCSS Properties
│   └── Manifest Schema
├── CLI Reference
│   ├── mosis init
│   ├── mosis build
│   ├── mosis sign
│   ├── mosis publish
│   └── ...
├── Best Practices
│   ├── Performance
│   ├── Security
│   ├── UX Guidelines
│   └── Accessibility
├── Troubleshooting
│   ├── Common Errors
│   ├── Debugging Tips
│   └── FAQ
└── Changelog

Content Types

Tutorials (Step-by-step)

# Build a Weather App

In this tutorial, you'll build a weather app that:
- Fetches weather data from an API
- Displays current conditions
- Shows a 5-day forecast
- Requests location permission

**Time:** 30 minutes
**Prerequisites:** Completed Quick Start

## Step 1: Create the Project

```bash
mosis init weather-app
cd weather-app

Step 2: Design the UI

Open assets/main.rml and add...


### Guides (Conceptual)

```markdown
# Understanding Permissions

Mosis uses a permission system to protect user privacy.
Apps must declare permissions in their manifest and
request them at runtime.

## Permission Categories

| Category | Description | Examples |
|----------|-------------|----------|
| Normal | Low risk, auto-granted | storage, network |
| Dangerous | User data, requires prompt | camera, location |
| Signature | System only | app_management |

## When Permissions Are Checked

Permissions are checked when your app calls...

API Reference (Technical)

# mosis.http

HTTP client for making network requests.

## Functions

### `mosis.http.get(url, options)`

Make a GET request.

**Parameters:**
- `url` (string): The URL to fetch
- `options` (table, optional):
  - `headers` (table): Request headers
  - `timeout` (number): Timeout in ms (default: 30000)

**Returns:** Promise that resolves to Response

**Example:**
```lua
local response = mosis.http.get("https://api.example.com/data")
if response.ok then
    local data = json.decode(response.body)
    print(data.name)
end

Errors:

NETWORK_ERROR: Network unavailable
TIMEOUT: Request timed out
INVALID_URL: Malformed URL


---

## Tech Stack Options

### Option A: Docusaurus

Framework: Docusaurus 3 Language: MDX (Markdown + React) Search: Algolia DocSearch Deploy: Vercel/Cloudflare Pages


| Pros | Cons |
|------|------|
| Versioning built-in | React knowledge needed |
| Great search | Can be heavy |
| Plugin ecosystem | |
| Used by many OSS | |

### Option B: VitePress

Framework: VitePress Language: Markdown + Vue Search: Built-in local search Deploy: Any static host


| Pros | Cons |
|------|------|
| Very fast | Fewer features |
| Vue-powered | Less ecosystem |
| Simple setup | |

### Option C: Astro Starlight

Framework: Astro + Starlight Language: MDX Search: Pagefind (local) Deploy: Any static host


| Pros | Cons |
|------|------|
| Very fast | Newer |
| Great defaults | Less customizable |
| Built-in i18n | |

### Option D: MkDocs Material

Framework: MkDocs Language: Markdown Search: Built-in Deploy: Any static host


| Pros | Cons |
|------|------|
| Simple | Less interactive |
| Great theme | Python-based |
| Fast builds | |

---

## Features Required

### Must Have

- [ ] Full-text search
- [ ] Syntax highlighting
- [ ] Mobile responsive
- [ ] Dark mode
- [ ] Version selector
- [ ] Edit on GitHub links
- [ ] Copy code buttons
- [ ] Table of contents
- [ ] Previous/Next navigation

### Nice to Have

- [ ] API playground
- [ ] Interactive examples
- [ ] Video tutorials
- [ ] Community translations
- [ ] Feedback widget

---

## Code Examples

### Runnable Examples

```html
<!-- Interactive code block -->
<CodePlayground language="lua">
local greeting = "Hello, Mosis!"
print(greeting)
</CodePlayground>

Multi-file Examples

:::code-group

```rml [main.rml]
<div id="counter">
    <span id="count">0</span>
    <button onclick="increment()">+</button>
</div>

local count = 0

function increment()
    count = count + 1
    document:GetElementById("count").inner_rml = tostring(count)
end

#counter {
    display: flex;
    gap: 10px;
}

:::


---

## API Documentation Generation

### From Lua Annotations

```lua
--- Make an HTTP GET request.
--- @param url string The URL to fetch
--- @param options? HttpOptions Request options
--- @return HttpResponse response The response object
--- @example
--- local resp = mosis.http.get("https://api.example.com/data")
--- print(resp.body)
function mosis.http.get(url, options)
    -- implementation
end

Generated Output

## `mosis.http.get(url, options?)`

Make an HTTP GET request.

### Parameters

| Name | Type | Description |
|------|------|-------------|
| url | string | The URL to fetch |
| options | HttpOptions? | Request options |

### Returns

`HttpResponse` - The response object

### Example

```lua
local resp = mosis.http.get("https://api.example.com/data")
print(resp.body)


---

## Versioning

### URL Structure

docs.mosis.dev/ # Latest stable docs.mosis.dev/v1.0/ # Version 1.0 docs.mosis.dev/v1.1/ # Version 1.1 docs.mosis.dev/next/ # Development (unreleased)


### Version Dropdown

┌────────────────────┐ │ Version: 1.1 (latest) ▼ │ ├────────────────────┤ │ 1.1 (latest) │ │ 1.0 │ │ next (unreleased) │ └────────────────────┘


---

## Search

### Algolia DocSearch (Free for OSS)

```javascript
// docusaurus.config.js
themeConfig: {
  algolia: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_KEY',
    indexName: 'mosis',
  },
}

Local Search (Pagefind)

// For Astro/VitePress
// Indexes at build time, searches client-side
// No external service needed

Internationalization

Directory Structure

docs/
├── en/
│   ├── getting-started/
│   └── guides/
├── es/
│   ├── getting-started/
│   └── guides/
└── zh/
    ├── getting-started/
    └── guides/

Language Switcher

┌──────────┐
│ 🌐 EN ▼  │
├──────────┤
│ English  │
│ Español  │
│ 中文     │
└──────────┘

Content Guidelines

Writing Style

Be concise - Get to the point quickly
Use active voice - "The function returns..." not "A value is returned..."
Show, don't tell - Code examples over explanations
Assume beginner - Don't assume prior knowledge
Test all examples - Every code block must work

Code Style

-- Good: Clear, commented
local response = mosis.http.get(API_URL)
if response.ok then
    local data = json.decode(response.body)
    updateUI(data)
else
    showError("Failed to load data")
end

-- Bad: Unclear, no error handling
local d = json.decode(mosis.http.get(u).body)

Screenshots

Use consistent device frame
Show relevant UI only
Add callouts for important areas
Keep file sizes small (WebP)

Deployment

CI/CD Pipeline

# .github/workflows/docs.yml
name: Deploy Docs

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install and Build
        run: |
          cd docs
          npm install
          npm run build

      - name: Deploy to Cloudflare Pages
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CF_API_TOKEN }}
          accountId: ${{ secrets.CF_ACCOUNT_ID }}
          projectName: mosis-docs
          directory: docs/build

Analytics

Track (Privacy-Friendly)

Page views (which docs are popular)
Search queries (what are people looking for)
404 pages (missing content)
Time on page (engagement)

Tools

Plausible (privacy-focused)
Simple Analytics
Cloudflare Analytics (free)

Feedback

Per-Page Feedback

┌────────────────────────────────────┐
│ Was this page helpful?             │
│                                    │
│ [👍 Yes]  [👎 No]                  │
│                                    │
│ [Edit this page on GitHub]         │
└────────────────────────────────────┘

Feedback Collection

// Send to analytics or issue tracker
function submitFeedback(page, helpful, comment) {
  fetch('/api/feedback', {
    method: 'POST',
    body: JSON.stringify({ page, helpful, comment })
  })
}

Deliverables

Framework selection
Information architecture
Getting Started content
UI design guides
Lua scripting guides
API reference (all namespaces)
CLI reference
Best practices
Search integration
Version selector
Deploy pipeline
Feedback system

Content Prioritization

Phase 1 (Launch)

Quick Start
Your First App
Project Structure
RML Basics
Lua Basics
API Reference (core APIs)
CLI Reference

Phase 2

Complete API Reference
All hardware guides
Best practices
Troubleshooting

Phase 3

Advanced guides
Video tutorials
Translations
Community contributions

Open Questions

Host docs separately or under main domain?
Community wiki/contributions?
Video tutorial platform (YouTube, embedded)?
Glossary/terminology page?

12 KiB Raw Blame History