docs: make README an Rmd

Author: machow

Makefile

@@ -20,6 +20,16 @@ dev-stop:
 $(RSC_API_KEYS): dev-start
 	python script/setup-rsconnect/dump_api_keys.py $@
 
+README.md: README.Rmd
+	jupytext --from Rmd --to ipynb --output - $^ \
+	| jupyter nbconvert \
+		--stdin --to markdown \
+		--execute \
+		--ExecutePreprocessor.kernel_name='venv-pins-python' \
+		--TagRemovePreprocessor.remove_all_outputs_tags='hide-cell' \
+		--TagRemovePreprocessor.remove_input_tags='hide-cell' \
+		--output $@
+
 test:
 	pytest
 

README.Rmd

@@ -0,0 +1,100 @@
+---
+jupyter:
+  jupytext:
+    text_representation:
+      extension: .Rmd
+      format_name: rmarkdown
+      format_version: '1.2'
+      jupytext_version: 1.13.6
+  kernelspec:
+    display_name: venv-pins-python
+    language: python
+    name: venv-pins-python
+---
+
+# pins-python
+
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/machow/pins-python/HEAD)
+
+The pins package publishes data, models, and other python objects, making it
+easy to share them across projects and with your colleagues. You can pin
+objects to a variety of pin *boards*, including folders (to share on a
+networked drive or with services like DropBox), RStudio Connect, and Amazon
+S3.
+Pins can be automatically versioned, making it straightforward to track changes,
+re-run analyses on historical data, and undo mistakes.
+
+## Installation
+
+```shell
+python -m pip install pins
+```
+
+## Usage
+
+See the [documentation](https://rstudio.github.io/pins-python) for getting started.
+
+To use the pins package, you must first create a pin board. A good place
+to start is `board_folder()`, which stores pins in a directory you
+specify. Here I’ll use a special version of `board_folder()` called
+`board_temp()` which creates a temporary board that’s automatically
+deleted when your R session ends. This is great for examples, but
+obviously you shouldn't use it for real work!
+
+```{python}
+import pins
+from pins.data import mtcars
+
+board = pins.board_temp()
+```
+
+You can “pin” (save) data to a board with the `.pin_write()` method. It requires three
+arguments: an object, a name, and a pin type:
+
+```{python}
+board.pin_write(mtcars.head(), "mtcars", type="csv")
+```
+
+Above, we saved the data as a CSV, but depending on
+what you’re saving and who else you want to read it, you might use the
+`type` argument to instead save it as a `joblib` or `arrow` file (NOTE: arrow is not yet supported).
+
+You can later retrieve the pinned data with `.pin_read()`:
+
+```{python}
+board.pin_read("mtcars")
+```
+
+A board on your computer is good place to start, but the real power of
+pins comes when you use a board that’s shared with multiple people. To
+get started, you can use `board_folder()` with a directory on a shared
+drive or in dropbox, or if you use [RStudio
+Connect](https://www.rstudio.com/products/connect/) you can use
+`board_rsconnect()`:
+
+```python
+# Note that this uses one approach to connecting,
+# the environment variables CONNECT_SERVER and CONNECT_API_KEY
+
+board = pins.board_rsconnect()
+board.pin_write(tidy_sales_data, "hadley/sales-summary", type="csv")
+```
+
+Then, someone else (or an automated report) can read and use your
+pin:
+
+```python
+board = board_rsconnect()
+board.pin_read("hadley/sales-summary")
+```
+
+You can easily control who gets to access the data using the RStudio
+Connect permissions pane.
+
+The pins package also includes boards that allow you to share data on
+services like Amazon’s S3 (`board_s3()`), with plans to support other backends--
+such as Azure's blob storage.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md)