Add docs (#17)

* initial docs + * match

* use mkdocs

* fix test gh action

Author: rmorshea

.github/workflows/test.yaml

@@ -1,6 +1,12 @@
 name: Test
 
-on: [push]
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
 
 jobs:
   coverage:

.gitignore

@@ -1,3 +1,7 @@
+# --- DOCS ---
+
+docs/site
+
 # --- JAVASCRIPT BUNDLES ---
 
 reactpy_router/bundle.js

README.md

@@ -2,60 +2,4 @@
 
 A URL router for ReactPy
 
-# Installation
-
-Use `pip` to install this package:
-
-```bash
-pip install reactpy-router
-```
-
-For a developer installation from source be sure to install [NPM](https://www.npmjs.com/) before running:
-
-```bash
-git clone https://github.com/reactive-python/reactpy-router
-cd reactpy-router
-pip install -e . -r requirements.txt
-```
-
-# Running the Tests
-
-To run the tests you'll need to install [Chrome](https://www.google.com/chrome/). Then you
-can download the [ChromeDriver](https://chromedriver.chromium.org/downloads) and add it to
-your `PATH`. Once that's done, simply `pip` install the requirements:
-
-```bash
-pip install -r requirements.txt
-```
-
-And run the tests with `pytest`:
-
-```bash
-pytest tests
-```
-
-You can run the tests in headless mode (i.e. without opening the browser):
-
-```bash
-pytest tests
-```
-
-You'll need to run in headless mode to execute the suite in continuous integration systems
-like GitHub Actions.
-
-# Releasing This Package
-
-To release a new version of reactpy-router on PyPI:
-
-1. Install [`twine`](https://twine.readthedocs.io/en/latest/) with `pip install twine`
-2. Update the `version = "x.y.z"` variable in `reactpy-router/__init__.py`
-3. `git` add the changes to `__init__.py` and create a `git tag -a x.y.z -m 'comment'`
-4. Build the Python package with `python setup.py sdist bdist_wheel`
-5. Check the build artifacts `twine check --strict dist/*`
-6. Upload the build artifacts to [PyPI](https://pypi.org/) `twine upload dist/*`
-
-To release a new version of `reactpy-router` on [NPM](https://www.npmjs.com/):
-
-1. Update `js/package.json` with new npm package version
-2. Clean out prior builds `git clean -fdx`
-3. Install and publish `npm install && npm publish`
+Read the docs: https://reactive-python.github.io/reactpy-router

docs/mkdocs.yml

@@ -0,0 +1,55 @@
+site_name: ReactPy Router
+docs_dir: src
+repo_url: https://github.com/reactive-python/reactpy-router
+
+nav:
+  - Home: index.md
+  - Usage: usage.md
+  - Tutorials:
+    - Simple Application: tutorials/simple-app.md
+    - Custom Router: tutorials/custom-router.md
+  - Reference: reference.md
+  - Contributing: contributing.md
+  - Source Code: https://github.com/reactive-python/reactpy-router
+
+theme:
+  name: material
+  logo: assets/logo.svg
+  favicon: assets/logo.svg
+  palette:
+    # Palette toggle for light mode
+    - scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+      primary: black
+      accent: light-blue
+
+    # Palette toggle for dark mode
+    - scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+      primary: black
+      accent: light-blue
+
+
+plugins:
+- search
+- mkdocstrings:
+    default_handler: python
+    handlers:
+      python:
+        paths: ["../"]
+        import:
+        - https://reactpy.dev/docs/objects.inv
+        - https://installer.readthedocs.io/en/stable/objects.inv
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+
+watch:
+  - "../reactpy_router"
+

docs/src/assets/logo.svg

@@ -0,0 +1,70 @@
+# Contributing
+
+!!! note
+
+    The [Code of Conduct](https://github.com/reactive-python/reactpy/blob/main/CODE_OF_CONDUCT.md)
+    applies in all community spaces. If you are not familiar with our Code of Conduct policy,
+    take a minute to read it before making your first contribution.
+
+The ReactPy team welcomes contributions and contributors of all kinds - whether they
+come as code changes, participation in the discussions, opening issues and pointing out
+bugs, or simply sharing your work with your colleagues and friends. We’re excited to see
+how you can help move this project and community forward!
+
+## Everyone Can Contribute!
+
+Trust us, there’s so many ways to support the project. We’re always looking for people who can:
+
+- Improve our documentation
+- Teach and tell others about ReactPy
+- Share ideas for new features
+- Report bugs
+- Participate in general discussions
+
+Still aren’t sure what you have to offer? Just [ask us](https://github.com/reactive-python/reactpy-router/discussions) and we’ll help you make your first contribution.
+
+## Development Environment
+
+For a developer installation from source be sure to install
+[NPM](https://www.npmjs.com/) before running:
+
+```bash
+git clone https://github.com/reactive-python/reactpy-router
+cd reactpy-router
+pip install -e . -r requirements.txt
+```
+
+This will install an ediable version of `reactpy-router` as well as tools you'll need
+to work with this project.
+
+Of particular note is [`nox`](https://nox.thea.codes/en/stable/), which is used to
+automate testing and other development tasks.
+
+## Running the Tests
+
+```bash
+nox -s test
+```
+
+You can run the tests with a headed browser.
+
+```bash
+nox -s test -- --headed
+```
+
+## Releasing This Package
+
+To release a new version of reactpy-router on PyPI:
+
+1. Install [`twine`](https://twine.readthedocs.io/en/latest/) with `pip install twine`
+2. Update the `version = "x.y.z"` variable in `reactpy-router/__init__.py`
+3. `git` add the changes to `__init__.py` and create a `git tag -a x.y.z -m 'comment'`
+4. Build the Python package with `python setup.py sdist bdist_wheel`
+5. Check the build artifacts `twine check --strict dist/*`
+6. Upload the build artifacts to [PyPI](https://pypi.org/) `twine upload dist/*`
+
+To release a new version of `reactpy-router` on [NPM](https://www.npmjs.com/):
+
+1. Update `js/package.json` with new npm package version
+2. Clean out prior builds `git clean -fdx`
+3. Install and publish `npm install && npm publish`

docs/src/contributing.md

@@ -0,0 +1,18 @@
+# ReactPy Router
+
+A URL router for [ReactPy](https://reactpy.dev).
+
+!!! note
+
+    If you don't already know the basics of working with ReactPy, you should
+    [start there](https://reactpy.dev/docs/guides/getting-started/index.html).
+
+## Installation
+
+Use `pip` to install this package:
+
+```bash
+pip install reactpy-router
+```
+
+[installer.records][]

docs/src/index.md

@@ -0,0 +1,5 @@
+# Reference
+
+::: reactpy_router.core
+::: reactpy_router.simple
+::: reactpy_router.types

docs/src/reference.md

@@ -0,0 +1,3 @@
+# Custom Router
+
+Under construction 🚧