Refactor some more docs

Archmonger · Archmonger · commit 78c7c4966d4b · 2024-10-05T23:43:23.000-07:00
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -1,147 +1,137 @@
 ---
 nav:
-    - Get Started:
-        - Add ReactPy-Router to Your Project: index.md
-        - Your First Routed Application: learn/your-first-app.md
-        - Advanced Topics:
-            - Routers, Routes, and Links: learn/routers-routes-and-links.md
-            - Hooks: learn/hooks.md
-            - Creating a Custom Router 🚧: learn/custom-router.md
-    - Reference:
-        - Core: reference/core.md
-        - Router: reference/router.md
-        - Types: reference/types.md
-    - About:
-        - Changelog: about/changelog.md
-        - Contributor Guide:
-            - Code: about/code.md
-            - Docs: about/docs.md
-        - Community:
-            - GitHub Discussions: https://github.com/reactive-python/reactpy-router/discussions
-            - Discord: https://discord.gg/uNb5P4hA9X
-            - Reddit: https://www.reddit.com/r/ReactPy/
-        - License: about/license.md
+  - Get Started:
+      - Add ReactPy-Router to Your Project: index.md
+      - Your First Routed Application: learn/your-first-app.md
+      - Advanced Topics:
+          - Routers, Routes, and Links: learn/routers-routes-and-links.md
+          - Hooks: learn/hooks.md
+          - Creating a Custom Router 🚧: learn/custom-router.md
+  - Reference:
+      - Router Components: reference/router.md
+      - Components: reference/components.md
+      - Hooks: reference/hooks.md
+      - Types: reference/types.md
+  - About:
+      - Changelog: about/changelog.md
+      - Contributor Guide:
+          - Code: about/code.md
+          - Docs: about/docs.md
+      - Community:
+          - GitHub Discussions: https://github.com/reactive-python/reactpy-router/discussions
+          - Discord: https://discord.gg/uNb5P4hA9X
+          - Reddit: https://www.reddit.com/r/ReactPy/
+      - License: about/license.md
 
 theme:
-    name: material
-    custom_dir: overrides
-    palette:
-        - media: "(prefers-color-scheme: dark)"
-          scheme: slate
-          toggle:
-              icon: material/white-balance-sunny
-              name: Switch to light mode
-          primary: red # We use red to indicate that something is unthemed
-          accent: red
-        - media: "(prefers-color-scheme: light)"
-          scheme: default
-          toggle:
-              icon: material/weather-night
-              name: Switch to dark mode
-          primary: white
-          accent: red
-    features:
-        - navigation.instant
-        - navigation.tabs
-        - navigation.tabs.sticky
-        - navigation.top
-        - content.code.copy
-        - search.highlight
-    icon:
-        repo: fontawesome/brands/github
-        admonition:
-            note: fontawesome/solid/note-sticky
-    logo: https://raw.githubusercontent.com/reactive-python/reactpy/main/branding/svg/reactpy-logo-square.svg
-    favicon: https://raw.githubusercontent.com/reactive-python/reactpy/main/branding/svg/reactpy-logo-square.svg
+  name: material
+  custom_dir: overrides
+  palette:
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/white-balance-sunny
+        name: Switch to light mode
+      primary: red # We use red to indicate that something is unthemed
+      accent: red
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+      primary: white
+      accent: red
+  features:
+    - navigation.instant
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.top
+    - content.code.copy
+    - search.highlight
+  icon:
+    repo: fontawesome/brands/github
+    admonition:
+      note: fontawesome/solid/note-sticky
+  logo: https://raw.githubusercontent.com/reactive-python/reactpy/main/branding/svg/reactpy-logo-square.svg
+  favicon: https://raw.githubusercontent.com/reactive-python/reactpy/main/branding/svg/reactpy-logo-square.svg
 
 markdown_extensions:
-    - toc:
-          permalink: true
-    - pymdownx.emoji:
-          emoji_index: !!python/name:material.extensions.emoji.twemoji
-          emoji_generator: !!python/name:material.extensions.emoji.to_svg
-    - pymdownx.tabbed:
-          alternate_style: true
-    - pymdownx.highlight:
-          linenums: true
-    - pymdownx.superfences
-    - pymdownx.details
-    - pymdownx.inlinehilite
-    - admonition
-    - attr_list
-    - md_in_html
-    - pymdownx.keys
+  - toc:
+      permalink: true
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.highlight:
+      linenums: true
+  - pymdownx.superfences
+  - pymdownx.details
+  - pymdownx.inlinehilite
+  - admonition
+  - attr_list
+  - md_in_html
+  - pymdownx.keys
 
 plugins:
-    - search
-    - include-markdown
-    - git-authors
-    - minify:
-          minify_html: true
-          minify_js: true
-          minify_css: true
-          cache_safe: true
-    - git-revision-date-localized:
-          fallback_to_build_date: true
-    - spellcheck:
-          known_words: dictionary.txt
-          allow_unicode: no
-          ignore_code: yes
-          skip_files:
-            - "index.md"
-            - "reference\\core.md"
-            - "reference/core.md"
-            - "reference\\types.md"
-            - "reference/types.md"
-    - mkdocstrings:
-          default_handler: python
-          handlers:
-              python:
-                  paths: ["../"]
-                  import:
-                      - https://reactpy.dev/docs/objects.inv
-                      - https://installer.readthedocs.io/en/stable/objects.inv
-
+  - search
+  - include-markdown
+  - git-authors
+  - minify:
+      minify_html: true
+      minify_js: true
+      minify_css: true
+      cache_safe: true
+  - git-revision-date-localized:
+      fallback_to_build_date: true
+  - spellcheck:
+      known_words: dictionary.txt
+      allow_unicode: no
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          paths: ["../"]
+          import:
+            - https://reactpy.dev/docs/objects.inv
+            - https://installer.readthedocs.io/en/stable/objects.inv
+          options:
+            show_root_heading: true
+            show_bases: false
 extra:
-    generator: false
-    version:
-        provider: mike
-    analytics:
-        provider: google
-        property: G-XRLQYZBG00
+  generator: false
+  version:
+    provider: mike
+  analytics:
+    provider: google
+    property: G-XRLQYZBG00
 
 extra_javascript:
-    - assets/js/main.js
+  - assets/js/main.js
 
 extra_css:
-    - assets/css/main.css
-    - assets/css/button.css
-    - assets/css/admonition.css
-    - assets/css/banner.css
-    - assets/css/sidebar.css
-    - assets/css/navbar.css
-    - assets/css/table-of-contents.css
-    - assets/css/code.css
-    - assets/css/footer.css
-    - assets/css/home.css
+  - assets/css/main.css
+  - assets/css/button.css
+  - assets/css/admonition.css
+  - assets/css/banner.css
+  - assets/css/sidebar.css
+  - assets/css/navbar.css
+  - assets/css/table-of-contents.css
+  - assets/css/code.css
+  - assets/css/footer.css
+  - assets/css/home.css
 
 watch:
-    - "../docs"
-    - ../README.md
-    - ../CHANGELOG.md
-    - ../LICENSE.md
-    - "../src"
+  - "../docs"
+  - ../README.md
+  - ../CHANGELOG.md
+  - ../LICENSE.md
+  - "../src"
 
 site_name: ReactPy Router
 site_author: Archmonger
 site_description: It's React-Router, but in Python.
-copyright: '&copy;
-<div id="year"></div>
-<script> document.getElementById("year").innerHTML = new Date().getFullYear(); </script>
-Reactive Python and affiliates.
-<div class="legal-footer-right">
-This project has no affiliation to ReactJS or Meta Platforms, Inc.
-</div>'
+copyright: '&copy;<div id="year"></div><script> document.getElementById("year").innerHTML = new Date().getFullYear(); </script>Reactive Python and affiliates.<div class="legal-footer-right">This project has no affiliation to ReactJS or Meta Platforms, Inc.</div>'
 repo_url: https://github.com/reactive-python/reactpy-router
 site_url: https://reactive-python.github.io/reactpy-router
 repo_name: ReactPy Router (GitHub)
diff --git a/docs/src/learn/hooks.md b/docs/src/learn/hooks.md
@@ -6,7 +6,7 @@ Several pre-fabricated hooks are provided to help integrate with routing feature
 
 ---
 
-## Use Search Params
+## Use Search Parameters
 
 The [`use_search_params`][src.reactpy_router.use_search_params] hook can be used to access query parameters from the current location. It returns a dictionary of query parameters, where each value is a list of strings.
 
diff --git a/docs/src/reference/components.md b/docs/src/reference/components.md
@@ -0,0 +1,4 @@
+::: src.reactpy_router
+
+    options:
+        members: ["route", "link"]
diff --git a/docs/src/reference/core.md b/docs/src/reference/core.md
diff --git a/docs/src/reference/hooks.md b/docs/src/reference/hooks.md
@@ -0,0 +1,4 @@
+::: src.reactpy_router
+
+    options:
+        members: ["use_params", "use_search_params"]
diff --git a/docs/src/reference/router.md b/docs/src/reference/router.md
@@ -1 +1,4 @@
-::: src.reactpy_router.browser_router
+::: src.reactpy_router
+
+    options:
+        members: ["browser_router"]
diff --git a/src/reactpy_router/__init__.py b/src/reactpy_router/__init__.py
@@ -7,7 +7,6 @@
     create_router,
     link,
     route,
-    router,
     use_params,
     use_search_params,
 )
@@ -21,7 +20,6 @@
     "route",
     "Route",
     "RouteCompiler",
-    "router",
     "RouteResolver",
     "browser_router",
     "use_params",
diff --git a/src/reactpy_router/core.py b/src/reactpy_router/core.py
@@ -31,7 +31,7 @@
 
 
 def route(path: str, element: Any | None, *routes: Route) -> Route:
-    """Create a route with the given path, element, and child routes"""
+    """Create a route with the given path, element, and child routes."""
     return Route(path, element, routes)
 
 
@@ -49,7 +49,10 @@ def router(
     *routes: R,
     compiler: RouteCompiler[R],
 ) -> VdomDict | None:
-    """A component that renders matching route(s) using the given compiler function."""
+    """A component that renders matching route(s) using the given compiler function.
+
+    This typically should never be used by a user. Instead, use `create_router` if creating
+    a custom routing engine."""
 
     old_conn = use_connection()
     location, set_location = use_state(old_conn.location)
@@ -82,11 +85,10 @@ def router(
 
 @component
 def link(*children: VdomChild, to: str, **attributes: Any) -> VdomDict:
-    """A component that renders a link to the given path.
-
-    FIXME: This currently works in a "dumb" way by trusting that ReactPy's script tag
-    properly sets the location. When a client-server communication layer is added to a
-    future ReactPy release, this component will need to be rewritten to use that instead."""
+    """A component that renders a link to the given path."""
+    # FIXME: This currently works in a "dumb" way by trusting that ReactPy's script tag \
+    # properly sets the location. When a client-server communication layer is added to a \
+    # future ReactPy release, this component will need to be rewritten to use that instead. \
     set_location = _use_route_state().set_location
     uuid = uuid4().hex
 
@@ -106,8 +108,8 @@ def on_click(_event: dict[str, Any]) -> None:
 
 
 def use_params() -> dict[str, Any]:
-    """The `use_params` hook returns an object of key/value pairs of the dynamic params \
-    from the current URL that were matched by the `Route`. Child routes inherit all params \
+    """The `use_params` hook returns an object of key/value pairs of the dynamic parameters \
+    from the current URL that were matched by the `Route`. Child routes inherit all parameters \
     from their parent routes.
 
     For example, if you have a `URL_PARAM` defined in the route `/example/<URL_PARAM>/`,
@@ -126,8 +128,8 @@ def use_search_params(
 ) -> dict[str, list[str]]:
     """
     The `use_search_params` hook is used to read and modify the query string in the URL \
-    for the current location. Like React's own `use_state` hook, `use_search_params returns \
-    an array of two values: the current location's search params and a function that may \
+    for the current location. Like React's own `use_state` hook, `use_search_params` returns \
+    an array of two values: the current location's search parameters and a function that may \
     be used to update them.
 
     See `urllib.parse.parse_qs` for info on this hook's parameters."""
diff --git a/src/reactpy_router/routers.py b/src/reactpy_router/routers.py
@@ -1,4 +1,4 @@
-"""A simple router implementation for ReactPy"""
+"""URL router implementation for ReactPy"""
 
 from __future__ import annotations
 
diff --git a/src/reactpy_router/types.py b/src/reactpy_router/types.py

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-"""A simple router implementation for ReactPy"""`
	`1`	`+"""URL router implementation for ReactPy"""`
`2`	`2`
`3`	`3`	`from __future__ import annotations`
`4`	`4`