Merge pull request #118 from rstudio/docs-readme

machow · web-flow · commit 4ea381e2eab1 · 2022-05-19T12:56:39.000-04:00
Docs readme
diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md
@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+codeofconduct@rstudio.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,75 @@
+# pins-python
+
+## Development
+
+### Install pins with dev dependencies
+
+```shell
+python -m pip install -e .[dev]
+```
+
+### Install pre-commit hooks
+
+This project uses [pre-commit](https://pre-commit.com/) to check and format each commit.
+
+You can set it up by running the following code in this repo:
+
+```
+python -m pip install pre-commit
+pre-commit install
+```
+
+### Setting version number
+
+This project uses [setuptools_scm](https://github.com/pypa/setuptools_scm) to
+automatically track and change version numbers within the `pins` package.
+It works by checking the last tagged commit.
+
+In order to set the version number, create a tag like the following.
+
+```shell
+git tag v0.0.1
+```
+
+In order to see the version number being used for the current commit, run:
+
+```
+python -m setuptools_scm
+```
+
+## Test
+
+Tests can be run using pytest:
+
+```shell
+pytest pins
+
+# run all tests except those for Rstudio Connect
+pytest pins -m 'not fs_rsc'
+
+# run only local filesystem backend tests
+pytest pins -m 'fs_file'
+```
+
+There are two important details to note for testing:
+
+* **Backends**. pins can write to backends like s3, azure, and RStudio Connect, so you
+    will need to set credentials to test against them.
+* **Pytest Marks**. You can disable tests over a specific backend through pytest's
+    `-m` flag. For example...
+  - Skip S3: `pytest pins -m 'not fs_s3'`
+  - Test only s3: `pytest pins -m 'fs_s3'`
+  - List all marks: `pytest pins --markers`
+
+### Configuring backends
+
+* Copy `.env.dev` to be `.env`
+* Modify `.env` to file in environment variables (e.g. AWS_ACCESS_KEY_ID)
+* Be careful not to put any sensitive information in `.env.dev`!
+
+### Setting up RStudio Connect tests
+
+```
+# Be sure to set RSC_LICENSE in .env
+make dev
+```
diff --git a/Makefile b/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
 
diff --git a/README.Rmd b/README.Rmd
@@ -0,0 +1,93 @@
+```{python tags=c("hide-cell")}
+# this keeps the pandas dataframe repr from spitting out scoped style tags
+# which don't render on github
+import pandas as pd
+pd.set_option("display.notebook_repr_html", False)
+```
+
+# 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 Python script or notebook 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)
diff --git a/README.md b/README.md
