docs: add reference index page

Author: machow

docs/_config.yml

@@ -33,6 +33,7 @@ html:
 
 sphinx:
   config:
+    add_module_names: true
     nb_custom_formats:
         .Rmd:
             - jupytext.reads

docs/api/boards.rst

@@ -1,5 +1,5 @@
-Board
-=====
+Board Methods
+=============
 
 .. currentmodule:: pins
 

docs/api/constructors.rst

@@ -0,0 +1,13 @@
+Board Constructors
+==================
+
+.. currentmodule:: pins
+
+.. autosummary::
+   :toctree: api_card/
+
+   ~board_folder
+   ~board_local
+   ~board_temp
+   ~board_s3
+   ~board_rsconnect

docs/api/filesystem.rst

@@ -1,9 +1,48 @@
 Reference
 =============
 
+Board Pin Methods
+-----------------
+
+.. table::
+   :class: table-align-left
+
+   ===========================================  =======================================================
+    :meth:`.pin_read`, :meth:`.pin_write`        |read-write|
+    :meth:`.pin_meta`                            |arrange|
+    :meth:`.pin_download`, :meth:`.pin_upload`   |select|
+    :meth:`.pin_versions`, TODO complete         |mutate|
+    :meth:`.pin_list`                            |summarize|
+    :meth:`.pin_search`                          |group_by|
+   ===========================================  =======================================================
+
+.. |read-write| replace:: Read and write objects to and from a board
+.. |arrange| replace:: Retrieve metadata for a pin
+.. |select| replace:: Upload and download files to and from a board
+.. |mutate| replace:: List, delete, and prune pin versions
+.. |summarize| replace:: List all pins
+.. |group_by| replace:: Search for pins
+
+
+Board Constructors
+------------------
+
+Boards abstract over different storage backends, making it easy to share data in a variety of ways.
+
+.. list-table::
+   :class: table-align-left
+
+   * - :func:`.board_folder`, :func:`board_local`
+     - Use a local folder as a board
+   * - :func:`.board_rsconnect`
+     - Use RStudio Connect as a board
+   * - :func:`.board_s3`
+     - Use an S3 bucket as a board
+
+
 .. toctree::
    :maxdepth: 2
 
+   constructors
    boards
    meta
-   filesystem

docs/api/index.rst

@@ -12,7 +12,7 @@ jupyter:
     name: venv-pins-python
 ---
 
-```{python tags=c(), nbsphinx="hidden"}
+```{python tags=c("remove-input"), nbsphinx="hidden"}
 import pandas as pd
 pd.options.display.max_rows = 25
 ```

docs/getting_started.Rmd

@@ -14,6 +14,12 @@ kernelspec:
 
 # Welcome
 
+```{image} logo.png
+:align: right
+:height: 139px
+:alt: pins, a library for organizing and sharing data.
+```
+
 The pins package publishes data, models, and other R 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, Amazon S3, Azure storage and ~Microsoft 365 (OneDrive and SharePoint)~.
 Pins can be automatically versioned, making it straightforward to track changes, re-run analyses on historical data, and undo mistakes.
@@ -64,9 +70,12 @@ To get started, you can use `board_folder()` with a directory on a shared drive
 +++
 
 ```python
-board <- board_rsconnect()
+from pins import board_rsconnect
+
+board = board_rsconnect()
 #> Connecting to RSC 1.9.0.1 at <https://connect.rstudioservices.com>
-board.pin_write(tidy_sales_data, "sales-summary", type = "rds")
+
+board.pin_write(tidy_sales_data, "sales-summary", type = "csv")
 #> Writing to pin 'hadley/sales-summary'
 ```
 

docs/intro.md

@@ -10,5 +10,14 @@
 
 # Imports ----
 from .boards import BaseBoard
-from .constructors import *
 from .cache import PinsCache, PinsUrlCache, cache_prune
+from .constructors import (
+    board_deparse,
+    board_folder,
+    board_temp,
+    board_local,
+    board_github,
+    board_urls,
+    board_rsconnect,
+    board_s3,
+)