Merge pull request #96 from machow/docs-homepage

Docs homepage

Author: machow

Makefile

@@ -24,10 +24,7 @@ test:
 	pytest
 
 docs-build:
-	cd docs && sphinx-build . ./_build/html $(SPHINX_BUILDARGS)
-
-docs-watch:
-	cd docs && sphinx-autobuild . ./_build/html $(SPHINX_BUILDARGS)
+	jb build --builder html docs
 
 docs-clean:
 	rm -rf docs/_build docs/api/api_card

docs/_config.yml

@@ -0,0 +1,44 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: Pins
+author: RStudio Inc.
+#logo: logo.png
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: force
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: book.tex
+
+# Add a bibtex file so that we can create citations
+bibtex_bibfiles:
+  - references.bib
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/machow/pins-python
+  path_to_book: docs
+  branch: main
+
+# Add GitHub buttons to your book
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+  use_issues_button: true
+  use_repository_button: true
+
+sphinx:
+  config:
+    add_module_names: true
+    nb_custom_formats:
+        .Rmd:
+            - jupytext.reads
+            - fmt: Rmd
+  extra_extensions:
+    - "sphinx.ext.napoleon"
+    - "sphinx.ext.autodoc"
+    - "sphinx.ext.autosummary"

docs/_toc.yml

@@ -0,0 +1,8 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: intro
+chapters:
+- file: getting_started
+- file: api/index.rst

docs/api/boards.rst

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

docs/api/constructors.rst

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

docs/api/filesystem.rst

@@ -1,9 +1,50 @@
-API
+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
+   * - :func:`.board`
+     - Generic board constructor
+
+
 .. 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
 ```