Merge pull request #198 from rstudio/quartodoc-attempt-1

Start transition to quartodoc

Author: machow

.github/workflows/ci.yml

@@ -79,20 +79,21 @@ jobs:
           no_proxy: "*"
 
   test-rsconnect:
-    name: "Test RSConnect"
+    name: "Test Posit Connect"
     runs-on: ubuntu-latest
     if: ${{ !github.event.pull_request.head.repo.fork }}
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2
         with:
-          python-version: 3.8
+          python-version: "3.10"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           python -m pip install -r requirements/dev.txt
           python -m pip install -e .[test]
-      - name: run RStudio Connect
+
+      - name: run Posit Connect
         run: |
           docker-compose up --build -d
           make dev
@@ -130,28 +131,27 @@ jobs:
     name: "Build Docs"
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
-
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
         with:
           python-version: "3.10"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           python -m pip install -r requirements/dev.txt
           python -m pip install -e .
-          ipython kernel install --name "venv-pins-python" --user
-      - uses: r-lib/actions/setup-pandoc@v1
-        with:
-          pandoc-version: '2.17.0.1'
+          python -m ipykernel install --user
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
       - name: Build docs
         run: |
           make docs-build
       - name: Save docs artifact
         uses: actions/upload-artifact@v3
         with:
           name: docs-html
-          path: docs/_build/html/
+          path: docs-quarto/_site
 
   preview-docs:
     name: "Preview Docs:"
@@ -163,7 +163,7 @@ jobs:
       - uses: actions/download-artifact@v3
         with:
           name: docs-html
-          path: docs-html
+          path: docs-quarto/_site
 
       # Determine the release name ---
 
@@ -193,7 +193,7 @@ jobs:
         run: |
           npm install -g netlify-cli
           # push main branch to production, others to preview --
-          netlify deploy --dir=docs-html --alias="${ALIAS}"
+          netlify deploy --dir=docs-quarto/_site --alias="${ALIAS}"
 
         env:
           NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
@@ -222,11 +222,11 @@ jobs:
       - uses: actions/download-artifact@v3
         with:
           name: docs-html
-          path: docs-html
+          path: docs-quarto/_site
       - uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs-html
+          publish_dir: docs-quarto/_site
 
   release-pypi:
     name: "Release to pypi"

.github/workflows/cross-compat.yml

@@ -52,7 +52,7 @@ jobs:
 
     - uses: actions/setup-python@v2
       with:
-        python-version: 3.8
+        python-version: "3.10"
     - name: Install py dependencies
       run: |
         python -m pip install --upgrade pip

.gitignore

@@ -137,3 +137,10 @@ dmypy.json
 # RStudio
 .Rproj.user
 *.Rproj
+
+# Quarto
+/.quarto/
+_site/
+objects.json
+reference/
+src/

Makefile

@@ -20,15 +20,8 @@ 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 $@
+README.md:
+	quarto render README.qmd
 
 test: test-most test-rsc
 
@@ -39,7 +32,8 @@ test-rsc:
 	pytest pins -m "fs_rsc"
 
 docs-build:
-	jb build --builder html docs
+	cd docs-quarto && python -m quartodoc build --verbose
+	cd docs-quarto && quarto render
 
 docs-clean:
 	rm -rf docs/_build docs/api/api_card

README.md

@@ -1,102 +1,101 @@
-# pins-python
+# pins
+<a href="https://rstudio.github.io/pins-python/"><img src="docs/logo.png" align="right" height="138" /></a>
 
-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), Posit Connect, Amazon
-S3, and Google Cloud Storage.
-Pins can be automatically versioned, making it straightforward to track changes,
-re-run analyses on historical data, and undo mistakes.
+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), Posit
+Connect, Amazon S3, and Google Cloud Storage. Pins can be automatically
+versioned, making it straightforward to track changes, re-run analyses
+on historical data, and undo mistakes.
 
-See the [documentation](https://rstudio.github.io/pins-python) for getting started.
+See the [documentation](https://rstudio.github.io/pins-python) for
+getting started.
+
+You can use pins from R as well as Python. For example, you can use one
+language to read a pin created with the other. Learn more about [pins
+for R](https://pins.rstudio.com).
 
 ## Installation
 
-```shell
+You can install the released version of vetiver from
+[PyPI](https://pypi.org/project/pins/):
+
+``` shell
 python -m pip install pins
 ```
 
-## Usage
+And the development version from
+[GitHub](https://github.com/rstudio/pins-python) with:
 
-See the [documentation](https://rstudio.github.io/pins-python) for getting started.
+``` shell
+python -m pip install git+https://github.com/rstudio/pins-python
+```
+
+## Usage
 
 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!
+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
+``` 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:
-
+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
+``` python
 board.pin_write(mtcars.head(), "mtcars", type="csv")
 ```
 
     Writing pin:
     Name: 'mtcars'
-    Version: 20230410T151442Z-120a5
-
-
-
+    Version: 20230523T115348Z-120a5
 
+    Meta(title='mtcars: a pinned 5 x 11 DataFrame', description=None, created='20230523T115348Z', pin_hash='120a54f7e0818041', file='mtcars.csv', file_size=249, type='csv', api_version=1, version=Version(created=datetime.datetime(2023, 5, 23, 11, 53, 48, 555797), hash='120a54f7e0818041'), tags=None, name='mtcars', user={}, local={})
 
-    Meta(title='mtcars: a pinned 5 x 11 DataFrame', description=None, created='20230410T151442Z', pin_hash='120a54f7e0818041', file='mtcars.csv', file_size=249, type='csv', api_version=1, version=Version(created=datetime.datetime(2023, 4, 10, 15, 14, 42, 55001), hash='120a54f7e0818041'), tags=None, name='mtcars', user={}, local={})
-
-
-
-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`, `parquet`, or `json` file.
+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`, `parquet`, or `json` file.
 
 You can later retrieve the pinned data with `.pin_read()`:
 
-
-```python
+``` python
 board.pin_read("mtcars")
 ```
 
-
-
-
         mpg  cyl   disp   hp  drat     wt   qsec  vs  am  gear  carb
     0  21.0    6  160.0  110  3.90  2.620  16.46   0   1     4     4
     1  21.0    6  160.0  110  3.90  2.875  17.02   0   1     4     4
     2  22.8    4  108.0   93  3.85  2.320  18.61   1   1     4     1
     3  21.4    6  258.0  110  3.08  3.215  19.44   1   0     3     1
     4  18.7    8  360.0  175  3.15  3.440  17.02   0   0     3     2
 
-
-
 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 [Posit
 Connect](https://posit.co/products/enterprise/connect/) you can use
 `board_connect()`:
 
-```python
+``` python
 # Note that this uses one approach to connecting,
 # the environment variables CONNECT_SERVER and CONNECT_API_KEY
 
 board = pins.board_connect()
 board.pin_write(tidy_sales_data, "hadley/sales-summary", type="csv")
 ```
 
-Then, someone else (or an automated report) can read and use your
-pin:
+Then, someone else (or an automated report) can read and use your pin:
 
-```python
+``` python
 board = board_connect()
 board.pin_read("hadley/sales-summary")
 ```
@@ -105,9 +104,14 @@ You can easily control who gets to access the data using the Posit
 Connect permissions pane.
 
 The pins package also includes boards that allow you to share data on
-services like Amazon’s S3 (`board_s3()`), Google Cloud Storage (`board_gcs()`),
-and Azure blob storage (`board_azure()`).
+services like Amazon’s S3 (`board_s3()`), Google Cloud Storage
+(`board_gcs()`), and Azure blob storage (`board_azure()`).
+
+## Contributing
 
-## Development
+- This project is released with a [Contributor Code of
+  Conduct](https://www.contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html).
+  By contributing to this project, you agree to abide by its terms.
 
-See [CONTRIBUTING.md](CONTRIBUTING.md)
+- If you think you have encountered a bug, please [submit an
+  issue](https://github.com/rstudio/pins-python/issues).

README.Rmd renamed to README.qmd

@@ -1,11 +1,16 @@
-```{python tags=c("hide-cell")}
+---
+format: gfm
+---
+
+```{python}
+#| include: false
 # 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
+# pins <a href="https://rstudio.github.io/pins-python/"><img src="docs/logo.png" align="right" height="138" /></a>
 
 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
@@ -17,15 +22,25 @@ re-run analyses on historical data, and undo mistakes.
 
 See the [documentation](https://rstudio.github.io/pins-python) for getting started.
 
+You can use pins from R as well as Python. For example, you can use one language
+to read a pin created with the other. Learn more about
+[pins for R](https://pins.rstudio.com).
+
 ## Installation
 
+You can install the released version of vetiver from [PyPI](https://pypi.org/project/pins/):
+
 ```shell
 python -m pip install pins
 ```
 
-## Usage
+And the development version from [GitHub](https://github.com/rstudio/pins-python) with:
 
-See the [documentation](https://rstudio.github.io/pins-python) for getting started.
+```shell
+python -m pip install git+https://github.com/rstudio/pins-python
+```
+
+## Usage
 
 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
@@ -88,6 +103,8 @@ The pins package also includes boards that allow you to share data on
 services like Amazon’s S3 (`board_s3()`), Google Cloud Storage (`board_gcs()`),
 and Azure blob storage (`board_azure()`).
 
-## Development
+## Contributing
+
+- This project is released with a [Contributor Code of Conduct](https://www.contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.
 
-See [CONTRIBUTING.md](CONTRIBUTING.md)
+- If you think you have encountered a bug, please [submit an issue](https://github.com/rstudio/pins-python/issues).

docs-quarto/.gitignore

@@ -0,0 +1 @@
+/.quarto/

docs-quarto/_extensions/machow/interlinks/.gitignore

@@ -0,0 +1,3 @@
+*.html
+*.pdf
+*_files/

docs-quarto/_extensions/machow/interlinks/_extension.yml

@@ -0,0 +1,7 @@
+title: Interlinks
+author: Michael Chow
+version: 1.0.0
+quarto-required: ">=1.2.0"
+contributes:
+  filters:
+    - interlinks.lua