docs(mkdocs): update Getting Started, Hello World, Components, and platform guides

owenthcarey · owenthcarey · commit 66e5eb1d7e61 · 2025-10-09T14:03:28.000-07:00
diff --git a/docs/concepts/components.md b/docs/concepts/components.md
@@ -29,3 +29,23 @@ class MainPage(pn.Page):
 Notes:
 - `pn.Page` stores the Android `Activity` so components like `pn.Button()` and `pn.Label()` can construct their native counterparts.
 - If you construct views before the `Page` is created on Android, a runtime error will be raised because no `Context` is available.
+
+## Core components (0.2.0)
+
+Stabilized with contextless constructors on both platforms:
+
+- `Page`
+- `StackView`
+- `Label`, `Button`
+- `ImageView`
+- `TextField`, `TextView`
+- `Switch`
+- `ProgressView`, `ActivityIndicatorView`
+- `WebView`
+
+APIs are intentionally small and grow progressively in later releases. Properties and setters are kept consistent where supported by both platforms.
+
+## Platform detection and Android context
+
+- Use `pythonnative.utils.IS_ANDROID` for platform checks when needed.
+- On Android, `Page` records the current `Activity` so child views can acquire a `Context` implicitly. Constructing views before `Page` initialization will raise.
diff --git a/docs/examples/hello-world.md b/docs/examples/hello-world.md
@@ -1,3 +1,30 @@
 # Hello World
 
-A minimal placeholder example. Replace with a real example later.
+Create a simple page with a label and a button.
+
+```python
+import pythonnative as pn
+
+
+class MainPage(pn.Page):
+    def __init__(self, native_instance):
+        super().__init__(native_instance)
+
+    def on_create(self):
+        super().on_create()
+        stack = pn.StackView()
+        label = pn.Label("Hello, world!")
+        button = pn.Button("Tap me")
+        button.set_on_click(lambda: print("Hello tapped"))
+        stack.add_view(label)
+        stack.add_view(button)
+        self.set_root_view(stack)
+```
+
+Run it:
+
+```bash
+pn run android
+# or
+pn run ios
+```
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -5,11 +5,63 @@ pip install pythonnative
 pn --help
 ```
 
-- Install: `pip install pythonnative`
-- Create a project: `pn init my_app`
-  - Scaffolds `app/`, `pythonnative.json`, `requirements.txt`, `.gitignore`
-- Run: `pn run android` or `pn run ios`
-  - Uses bundled templates; copies your `app/` into the platform project
-  - On Android, `pn.Page` provides the Activity context so components can be created without passing a context
-- Clean: `pn clean`
-  - Removes the `build/` directory safely
+## Create a project
+
+```bash
+pn init MyApp
+```
+
+This scaffolds:
+
+- `app/` with a minimal `main_page.py`
+- `pythonnative.json` project config
+- `requirements.txt`
+- `.gitignore`
+
+A minimal `app/main_page.py` looks like:
+
+```python
+import pythonnative as pn
+
+
+class MainPage(pn.Page):
+    def __init__(self, native_instance):
+        super().__init__(native_instance)
+
+    def on_create(self):
+        super().on_create()
+        stack = pn.StackView()
+        stack.add_view(pn.Label("Hello from PythonNative!"))
+        button = pn.Button("Tap me")
+        button.set_on_click(lambda: print("Button clicked"))
+        stack.add_view(button)
+        self.set_root_view(stack)
+```
+
+## Run on a platform
+
+```bash
+pn run android
+# or
+pn run ios
+```
+
+- Uses bundled templates (no network required for scaffolding)
+- Copies your `app/` into the generated project
+
+If you just want to scaffold the platform project without building, use:
+
+```bash
+pn run android --prepare-only
+pn run ios --prepare-only
+```
+
+This stages files under `build/` so you can open them in Android Studio or Xcode.
+
+## Clean
+
+Remove the build artifacts safely:
+
+```bash
+pn clean
+```
diff --git a/docs/guides/android.md b/docs/guides/android.md
@@ -21,3 +21,16 @@ pn run android --prepare-only
 ```
 
 This will stage files under `build/android/android_template` so you can open it in Android Studio if you prefer.
+
+## Clean
+
+Remove the build directory safely:
+
+```bash
+pn clean
+```
+
+## Troubleshooting
+
+- If `gradlew` fails due to JDK path on macOS, ensure `JAVA_HOME` is set (the CLI attempts to detect Homebrew `openjdk@17`).
+- Ensure an Android emulator or device is available for `installDebug`.
diff --git a/docs/guides/ios.md b/docs/guides/ios.md
@@ -21,3 +21,15 @@ pn run ios --prepare-only
 ```
 
 You can then open `build/ios/ios_template/ios_template.xcodeproj` in Xcode.
+
+## Clean
+
+Remove the build directory safely:
+
+```bash
+pn clean
+```
+
+## Notes
+
+- Building and running for Simulator via the CLI is best-effort. Opening the generated project in Xcode is recommended for iterative development.
