Add docs #17

rmorshea · 2023-05-11T06:19:07Z

closes: #1

Archmonger · 2023-05-11T21:56:49Z

README.md

+@component
+def root():
+    return simple.router(
+        route("/", home()),
+        route(
+            "/messages",
+            all_messages(),
+            # we'll improve upon these manually created routes in the next section...
+            route("/with/Alice", messages_with("Alice")),
+            route("/with/Alice-Bob", messages_with("Alice", "Bob")),
+        ),
+        route("*", html.h1("Missing Link 🔗‍💥")),
+    )
+
+@component
+def home():
+    return html.div(
+        html.h1("Home Page 🏠"),
+        link("Messages", to="/messages"),
+    )
+
+@component
+def all_messages():
+    last_messages = {
+        ", ".join(msg["with"]): msg
+        for msg in sorted(message_data, key=lambda m: m["id"])
+    }
+    return html.div(
+        html.h1("All Messages 💬"),
+        html.ul(
+            [
+                html.li(
+                    {"key": msg["id"]},
+                    html.p(
+                        link(
+                            f"Conversation with: {', '.join(msg['with'])}",
+                            to=f"/messages/with/{'-'.join(msg['with'])}",
+                        ),
+                    ),
+                    f"{'' if msg['from'] is None else '🔴'} {msg['message']}",
+                )
+                for msg in last_messages.values()
+            ]
+        ),
+    )
+
+@component
+def messages_with(*names):
+    names = set(names)
+    messages = [msg for msg in message_data if set(msg["with"]) == names]
+    return html.div(
+        html.h1(f"Messages with {', '.join(names)} 💬"),
+        html.ul(
+            [
+                html.li(
+                    {"key": msg["id"]},
+                    f"{msg['from'] or 'You'}: {msg['message']}",
+                )
+                for msg in messages
+            ]
+        ),
+    )


I think defining messages_with, all_messages, and message_data is overkill. Ends up distracting from the point (nested routes).

Since this is simply for demonstration purposes, I would either rewrite messages_with and all_messages to return one-liner dummy strings, or not use components at all and directly put raw strings into the routes (ex. html.p("EXAMPLE: All Messages")).

Archmonger · 2023-05-11T21:59:49Z

README.md

+```
+
+In this case, `param` is the name of the route parameter and the optionally declared
+`type` specifies what kind of parameter it is. The available parameter types and what
+patterns they match are are:
+
+- str (default) - `[^/]+`
+- int - `\d+`
+- float - `\d+(\.\d+)?`
+- uuid - `[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}`
+- path - `.+`
+
+Any parameters that have matched in the currently displayed route can then be consumed
+with the `use_params` hook which returns a dictionary mapping the parameter names to
+their values. Note that parameters with a declared type will be converted to is in the
+parameters dictionary. So for example `/my/route/{my_param:float}` would match
+`/my/route/3.14` and have a parameter dictionary of `{"my_param": 3.14}`.
+
+If we take this information and apply it to our growing example application we'd
+substitute the manually constructed `/messages/with` routes with a single
+`/messages/with/{names}` route:
+
+```python
+from reactpy import component, html, run
+from reactpy_router import route, simple, link
+from reactpy_router.core import use_params
+
+message_data = [
+    {"id": 1, "with": ["Alice"], "from": None, "message": "Hello!"},
+    {"id": 2, "with": ["Alice"], "from": "Alice", "message": "How's it going?"},
+    {"id": 3, "with": ["Alice"], "from": None, "message": "Good, you?"},
+    {"id": 4, "with": ["Alice"], "from": "Alice", "message": "Good, thanks!"},
+    {"id": 5, "with": ["Alice", "Bob"], "from": None, "message": "We meeting now?"},
+    {"id": 6, "with": ["Alice", "Bob"], "from": "Alice", "message": "Not sure."},
+    {"id": 7, "with": ["Alice", "Bob"], "from": "Bob", "message": "I'm here!"},
+    {"id": 8, "with": ["Alice", "Bob"], "from": None, "message": "Great!"},
+]
+
+@component
+def root():
+    return simple.router(
+        route("/", home()),
+        route(
+            "/messages",
+            all_messages(),
+            route("/with/{names}", messages_with()),  # note the path param
+        ),
+        route("*", html.h1("Missing Link 🔗‍💥")),
+    )
+
+@component
+def home():
+    return html.div(
+        html.h1("Home Page 🏠"),
+        link("Messages", to="/messages"),
+    )
+
+@component
+def all_messages():
+    last_messages = {
+        ", ".join(msg["with"]): msg
+        for msg in sorted(message_data, key=lambda m: m["id"])
+    }
+    return html.div(
+        html.h1("All Messages 💬"),
+        html.ul(
+            [
+                html.li(
+                    {"key": msg["id"]},
+                    html.p(
+                        link(
+                            f"Conversation with: {', '.join(msg['with'])}",
+                            to=f"/messages/with/{'-'.join(msg['with'])}",
+                        ),
+                    ),
+                    f"{'' if msg['from'] is None else '🔴'} {msg['message']}",
+                )
+                for msg in last_messages.values()
+            ]
+        ),
+    )
+
+@component
+def messages_with():
+    names = set(use_params()["names"].split("-"))  # and here we use the path param
+    messages = [msg for msg in message_data if set(msg["with"]) == names]
+    return html.div(
+        html.h1(f"Messages with {', '.join(names)} 💬"),
+        html.ul(
+            [
+                html.li(
+                    {"key": msg["id"]},
+                    f"{msg['from'] or 'You'}: {msg['message']}",
+                )
+                for msg in messages
+            ]
+        ),
+    )
+
+run(root)


This section is WAY too long to explain the simple concept of encoding parameters. Needs to be rewritten with the most basic example possible.

Just need to get the idea across that parameters turn into args (maybe they can also become kwargs?)

You're right. I think what I've written here is too long for a quick README that covers the features at a glance. However, this would still be useful to preserve, if explanations were expanded upon a bit, as a more in-depth tutorial. Is this something that you'd be comfortable with reworking, maybe with mkdocs?

Yeah when I get around to adding proper docs for this, I'll reference the commit log on this PR to fetch these examples. ReactPy docs and conreq dev comes first though.

rmorshea · 2023-05-25T06:12:21Z

Just switched the docs to mkdocs. Gonna merge as-is for now.

initial docs + * match

78dc291

rmorshea force-pushed the add-docs branch from 9bd9934 to 78dc291 Compare May 11, 2023 06:20

rmorshea requested a review from Archmonger May 11, 2023 06:22

Archmonger requested changes May 11, 2023

View reviewed changes

use mkdocs

16d4529

rmorshea closed this May 25, 2023

rmorshea reopened this May 25, 2023

fix test gh action

f1ac7a1

rmorshea merged commit b736c04 into reactive-python:main May 25, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add docs #17

Add docs #17

rmorshea commented May 11, 2023 •

edited

Loading

Archmonger May 11, 2023 •

edited

Loading

Archmonger May 11, 2023 •

edited

Loading

rmorshea May 11, 2023

Archmonger May 11, 2023 •

edited

Loading

rmorshea commented May 25, 2023

Add docs #17

Add docs #17

Conversation

rmorshea commented May 11, 2023 • edited Loading

Archmonger May 11, 2023 • edited Loading

Choose a reason for hiding this comment

Archmonger May 11, 2023 • edited Loading

Choose a reason for hiding this comment

rmorshea May 11, 2023

Choose a reason for hiding this comment

Archmonger May 11, 2023 • edited Loading

Choose a reason for hiding this comment

rmorshea commented May 25, 2023

rmorshea commented May 11, 2023 •

edited

Loading

Archmonger May 11, 2023 •

edited

Loading

Archmonger May 11, 2023 •

edited

Loading

Archmonger May 11, 2023 •

edited

Loading