Describe developer setup in more detail (#1859)

Author: mccalluc

README.md

@@ -58,7 +58,7 @@ git fetch --tags upstream
 Then install:
 
 ```sh
-pip install -e ".[dev,test]"
+pip install -e ".[dev,test,doc]"
 ```
 
 Additionally, you can install pre-commit hooks which will automatically reformat and lint the code when you make a commit:
@@ -69,3 +69,29 @@ pre-commit install
 # To disable:
 # pre-commit uninstall
 ```
+
+Tests should now pass:
+
+```sh
+make check
+# To apply formatting fixes instead of erroring:
+# make check-fix
+```
+
+Or get a full list of helpers with just:
+
+```sh
+make
+```
+
+Typically, when developing new features for Shiny, you'll want to try them out in an application.
+In a **separate** application directory, use can use `-e` to reference your local checkout of `py-shiny`:
+
+```sh
+# Rather than
+#   pip install shiny
+# run:
+pip install -e ../py-shiny --config-settings editable_mode=compat
+```
+
+See the [docs README](docs/README.md) for instructions on building the documentation locally.

docs/README.md

@@ -5,7 +5,7 @@ This directory contains files to generate Shiny for Python API documentation, us
 
 ## Building the docs
 
-To build the docs, first install the Python dependencies and Quarto extensions:
+To build the docs, first [download and install Quarto](https://quarto.org/docs/get-started/), and then install the Python dependencies and Quarto extensions:
 
 ```bash
 # Install build dependencies
@@ -18,14 +18,14 @@ After those dependencies are installed, build the .qmd files for Shiny, using qu
 make quartodoc
 ```
 
-Then build the web site using Quarto:
+Then you can build the docs, and serve them locally, and watch for changes to the .qmd files:
 
 ```bash
-make site
+make serve
 ```
 
-Alternatively, running `make serve` will build the docs, and serve them locally, and watch for changes to the .qmd files:
+Alternatively, build the site just once:
 
 ```bash
-make serve
+make site
 ```