FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

docs: adopt Google-style docstrings; revamp MkDocs site · pythonnative/pythonnative@922ec94 · GitHub

/ pythonnative Public

Commit 922ec94

Browse files
owenthcarey
committed
docs: adopt Google-style docstrings; revamp MkDocs site
1 parent ded782e commit 922ec94

70 files changed

Lines changed: 5598 additions & 878 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/docs.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ name: Docs
33
on:
44
push:
55
branches: [ main ]
6+
pull_request:
7+
branches: [ '**' ]
68

79
permissions:
810
contents: write
@@ -23,6 +25,7 @@ jobs:
2325
run: |
2426
python -m mkdocs build --strict
2527
- name: Deploy to GitHub Pages
28+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
2629
uses: peaceiris/actions-gh-pages@v3
2730
with:
2831
github_token: ${{ secrets.GITHUB_TOKEN }}

‎CONTRIBUTING.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,11 @@ cd examples/hello-world && pn run android
5454
- Prefer explicit, descriptive names; keep platform abstractions clean.
5555
- Add/extend tests under `tests/` for new behavior.
5656
- Do not commit generated artifacts or large binaries; templates live under `templates/`.
57+
- Docstrings: Google style throughout. Ruff is configured with the Google
58+
convention (`pydocstyle.convention = "google"`) and enforces the `D` rule
59+
set on `src/pythonnative/`. See the
60+
[Documentation style guide](https://docs.pythonnative.com/meta/style-guide/)
61+
for examples and Markdown/grammar conventions.
5762

5863
Common commands:
5964

@@ -291,7 +296,7 @@ Test flows live in `tests/e2e/flows/` and cover main page rendering, counter int
291296
- **E2E** (`e2e.yml`): builds the hello-world example on Android (Linux emulator) and iOS (macOS simulator), then runs Maestro flows. Triggers on pushes to `main`, PRs, and manual dispatch.
292297
- **PR Lint** (`pr-lint.yml`): validates the PR title against Conventional Commits format (protects squash merges) and checks individual commit messages via commitlint (protects rebase merges). Recommended: add the **PR title** job as a required status check in branch-protection settings.
293298
- **Release** (`release.yml`): runs on merge to `main`; computes version, generates changelog, tags, creates GitHub Release, and (when `DRAFT_RELEASE` is `"false"`) publishes to PyPI.
294-
- **Docs** (`docs.yml`): deploys documentation to GitHub Pages on push to `main`.
299+
- **Docs** (`docs.yml`): builds the MkDocs site in strict mode on every push and pull request, and deploys to GitHub Pages on push to `main`.
295300

296301
## Security and provenance
297302

‎docs/api/cli.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# CLI (`pn`)
2+
3+
Reference for the `pn` console script. The implementation lives in
4+
`pythonnative.cli.pn`; this page renders its docstrings directly so
5+
the documented behavior never drifts from the code.
6+
7+
## Subcommands
8+
9+
- `pn init [name]`: scaffold a new project (creates `app/`,
10+
`pythonnative.json`, `requirements.txt`, `.gitignore`).
11+
- `pn run android|ios`: build and run on a connected device or
12+
simulator. Flags: `--prepare-only`, `--hot-reload`, `--no-logs`.
13+
- `pn clean`: remove the local `build/` directory.
14+
15+
::: pythonnative.cli.pn
16+
options:
17+
show_root_heading: false
18+
show_root_toc_entry: false
19+
members_order: source
20+
filters: ["!^_"]
21+
22+
## Next steps
23+
24+
- See the [Getting started](../getting-started.md) walkthrough.
25+
- Read about [Hot reload](../guides/hot-reload.md) when you turn on
26+
`--hot-reload`.

‎docs/api/components.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Components
2+
3+
Element factory functions for the built-in PythonNative widgets. These
4+
return immutable [`Element`][pythonnative.Element] descriptors; nothing
5+
is mounted to a native view tree until the
6+
[`Reconciler`][pythonnative.reconciler.Reconciler] processes them.
7+
8+
For the visual and layout properties accepted by each component's
9+
`style` argument, see the
10+
[Component Property Reference](component-properties.md).
11+
12+
::: pythonnative.components
13+
options:
14+
show_root_heading: false
15+
show_root_toc_entry: false
16+
members_order: source
17+
filters: ["!^_"]
18+
19+
## Next steps
20+
21+
- Wire interactions with [Hooks](hooks.md).
22+
- Compose styles with [`StyleSheet`][pythonnative.StyleSheet].
23+
- Build navigation with [`NavigationContainer`][pythonnative.NavigationContainer].

‎docs/api/element.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Element
2+
3+
Immutable descriptor for a single node in PythonNative's virtual view
4+
tree. `Element` instances are produced by the
5+
[component factories](components.md) and consumed by the
6+
[`Reconciler`][pythonnative.reconciler.Reconciler].
7+
8+
You almost never construct an `Element` by hand; the factory functions
9+
exist precisely so app code stays in plain Python.
10+
11+
::: pythonnative.element
12+
options:
13+
show_root_heading: false
14+
show_root_toc_entry: false
15+
members_order: source
16+
filters: ["!^_"]
17+
18+
## Next steps
19+
20+
- See how trees of elements get mounted in
21+
[Reconciliation](../concepts/reconciliation.md).
22+
- Browse the built-in element types in [Components](components.md).

‎docs/api/hooks.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Hooks
2+
3+
Hook primitives for `@component` functions: state, effects, memoization,
4+
context, and refs. Hooks must be called at the top level of a component
5+
(not inside conditionals or loops) so they can be matched to the same
6+
slot across renders.
7+
8+
::: pythonnative.hooks
9+
options:
10+
show_root_heading: false
11+
show_root_toc_entry: false
12+
members_order: source
13+
filters: ["!^_"]
14+
15+
## Next steps
16+
17+
- Compose hooks into a screen: [Components](components.md).
18+
- Run side effects from
19+
[`use_effect`][pythonnative.use_effect] (after commit) and
20+
[`use_focus_effect`][pythonnative.use_focus_effect] (after focus).
21+
- Share state across the tree with
22+
[`create_context`][pythonnative.create_context] and
23+
[`Provider`][pythonnative.Provider].

‎docs/api/hot_reload.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Hot reload
2+
3+
Hot-reload comes in two cooperating pieces: a host-side file watcher
4+
that pushes changed `.py` files to the device, and a device-side
5+
module reloader that swaps the new code in and re-renders the active
6+
page. Both are wired up automatically by `pn run --hot-reload`.
7+
8+
::: pythonnative.hot_reload
9+
options:
10+
show_root_heading: false
11+
show_root_toc_entry: false
12+
members_order: source
13+
filters: ["!^_"]
14+
15+
## Next steps
16+
17+
- See the workflow in [Hot reload guide](../guides/hot-reload.md).

‎docs/api/native_modules.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Native modules
2+
3+
Cross-platform wrappers around device APIs that are not part of the
4+
view tree: camera and photo gallery, GPS, app-scoped file I/O, and
5+
local notifications. Each module is implemented twice (once per
6+
platform) and dispatches at runtime based on the `IS_ANDROID` and
7+
`IS_IOS` flags from `pythonnative.utils`.
8+
9+
::: pythonnative.native_modules
10+
options:
11+
show_root_heading: false
12+
show_root_toc_entry: false
13+
members_order: source
14+
filters: ["!^_"]
15+
16+
## Camera
17+
18+
::: pythonnative.native_modules.camera
19+
options:
20+
show_root_heading: false
21+
show_root_toc_entry: false
22+
members_order: source
23+
filters: ["!^_"]
24+
25+
## Location
26+
27+
::: pythonnative.native_modules.location
28+
options:
29+
show_root_heading: false
30+
show_root_toc_entry: false
31+
members_order: source
32+
filters: ["!^_"]
33+
34+
## File system
35+
36+
::: pythonnative.native_modules.file_system
37+
options:
38+
show_root_heading: false
39+
show_root_toc_entry: false
40+
members_order: source
41+
filters: ["!^_"]
42+
43+
## Notifications
44+
45+
::: pythonnative.native_modules.notifications
46+
options:
47+
show_root_heading: false
48+
show_root_toc_entry: false
49+
members_order: source
50+
filters: ["!^_"]
51+
52+
## Next steps
53+
54+
- See guidance and permission setup in [Native modules guide](../guides/native-modules.md).

‎docs/api/native_views.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Native views
2+
3+
The bridge between PythonNative's element tree and concrete native
4+
widgets. Every element type maps to a
5+
[`ViewHandler`][pythonnative.native_views.base.ViewHandler]
6+
implementation in the
7+
[`NativeViewRegistry`][pythonnative.native_views.NativeViewRegistry];
8+
the platform-specific handlers are registered lazily so importing
9+
`pythonnative` on the desktop never pulls in Chaquopy or rubicon-objc.
10+
11+
::: pythonnative.native_views
12+
options:
13+
show_root_heading: false
14+
show_root_toc_entry: false
15+
members_order: source
16+
filters: ["!^_"]
17+
18+
## Base classes
19+
20+
::: pythonnative.native_views.base
21+
options:
22+
show_root_heading: false
23+
show_root_toc_entry: false
24+
members_order: source
25+
filters: ["!^_"]
26+
27+
!!! note "Platform handlers"
28+
The Android and iOS handler implementations live in
29+
`pythonnative.native_views.android` and
30+
`pythonnative.native_views.ios` respectively. They are imported
31+
only at runtime on the corresponding platform; we don't render
32+
their API tables here because they're internal to the runtime and
33+
require platform-only dependencies (Chaquopy / rubicon-objc) to
34+
be importable for `mkdocstrings` to introspect them.
35+
36+
## Next steps
37+
38+
- Read the high-level model in
39+
[Native views (concept)](../concepts/native-views.md).
40+
- See how the reconciler drives handlers in [Reconciler](reconciler.md).

‎docs/api/navigation.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Navigation
2+
3+
The declarative navigation API: a single
4+
[`NavigationContainer`][pythonnative.NavigationContainer] holds one or
5+
more navigators (stack, tab, or drawer), and any descendant function
6+
component can navigate via
7+
[`use_navigation`][pythonnative.use_navigation] or read its current
8+
route with [`use_route`][pythonnative.use_route].
9+
10+
::: pythonnative.navigation
11+
options:
12+
show_root_heading: false
13+
show_root_toc_entry: false
14+
members_order: source
15+
filters: ["!^_"]
16+
17+
## Next steps
18+
19+
- See worked examples in [Navigation guide](../guides/navigation.md).
20+
- Inspect the imperative handle returned by
21+
[`use_navigation`][pythonnative.use_navigation].

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL