Merge pull request #153 from rstudio/quartodoc

Author: isabelizimm

.github/workflows/docs.yml

@@ -20,29 +20,31 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install -e .[dev]
+          python -m pip install -e .[docs]
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
       - name: build docs
         run: |
           make docs
       - name: save docs
         uses: actions/upload-artifact@v3
         with:
           name: docs-html
-          path: docs/_build/html/
+          path: docs/_site
       - name: publish dev docs
         if: github.ref_name == 'main' && github.ref_type == 'branch'
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/_build/*
+          publish_dir: docs/_site/*
           publish_branch: gh-pages
           destination_dir: main
       - name: publish stable docs
         if: github.ref_type == 'tag' && startswith(github.ref, 'refs/tags/v')
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/_build/*
+          publish_dir: docs/_site/*
           publish_branch: gh-pages
           destination_dir: ${{ github.ref_name }}
       - name: create symlink stable to new version

.gitignore

@@ -142,3 +142,5 @@ NOTES.md
 ## RStudio
 *.Rproj
 .Rproj.user
+
+/.quarto/

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 
 
-exclude: "(.*\\.csv)|(^examples/)|(^vetiver/tests/snapshots/)"
+exclude: "(.*\\.csv)|(^examples/)|(^vetiver/tests/snapshots/)|(^docs/_extensions/)"
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v2.4.0

Makefile

@@ -1,10 +1,6 @@
 .PHONY: clean-pyc clean-build clean docs
 UNAME := $(shell uname)
 
-SPHINX_BUILDARGS=
-# Note that these are keys generated by the docker rsconnect service, so are
-# not really secrets. They are saved to json to make it easy to use rsconnect
-# as multiple users from the tests
 RSC_API_KEYS=vetiver/tests/rsconnect_api_keys.json
 
 ifeq ($(UNAME), Darwin)
@@ -22,16 +18,15 @@ help:
 	@echo "test - run tests quickly with the default Python"
 	@echo "test-rsc - run tests for rsconnect"
 	@echo "coverage - check code coverage quickly with the default Python"
-	@echo "docs - generate Sphinx HTML documentation, including API docs"
-	@echo "cdocs - cleanout previous build & generate Sphinx HTML documentation, including API docs"
+	@echo "docs - generate HTML documentation, including API docs"
 	@echo "release - package and upload a release"
 	@echo "dist - package"
 	@echo "install - install the package to the active Python's site-packages"
 	@echo "dev - generate RStudio Connect API keys"
 	@echo "dev-start - start up development RStudio Connect in Docker"
 	@echo "dev-stop - stop RStudio Connect dev container"
 
-clean: clean-build clean-pyc clean-test docs-clean
+clean: clean-build clean-pyc clean-test
 
 clean-build:
 	rm -fr build/
@@ -65,14 +60,8 @@ coverage:
 	coverage html
 	$(BROWSER) htmlcov/index.html
 
-cdocs cdoc cdocumentation: docs-clean docs
-
-docs-clean:
-	$(MAKE) -C docs clean
-
 docs doc documentation:
-	$(MAKE) -C docs html
-	$(BROWSER) docs/_build/html/index.html
+	$(MAKE) -C docs docs
 
 release: dist
 	twine upload dist/*

docs/.gitignore

@@ -0,0 +1,8 @@
+/.quarto/
+/_site/
+/objects.json
+/_sidebar.yml
+/reference
+/latest
+/stable
+/_environment

docs/Makefile

@@ -1,20 +1,10 @@
-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = _build
-
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+# Minimal makefile for quartodoc documentation
 
 .PHONY: help Makefile
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+# Catch-all target:
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	python version_config.py
+	python -m quartodoc build
+	python -m quartodoc interlinks
+	quarto render

docs/_extensions/machow/interlinks/.gitignore

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

docs/_extensions/machow/interlinks/README.md

@@ -0,0 +1,30 @@
+# Interlinks Extension For Quarto
+
+_TODO_: Add a short description of your extension.
+
+## Installing
+
+_TODO_: Replace the `<github-organization>` with your GitHub organization.
+
+```bash
+quarto add <github-organization>/interlinks
+```
+
+This will install the extension under the `_extensions` subdirectory.
+If you're using version control, you will want to check in this directory.
+
+## Using
+
+_TODO_: Describe how to use your extension.
+
+## Example
+
+Here is the source code for a minimal example: [example.qmd](example.qmd).
+
+## Developing
+
+To see the AST the filter operates on, use this command:
+
+```
+quarto render example.qmd --to native --output -
+```

docs/_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.py

docs/_extensions/machow/interlinks/example.qmd

@@ -0,0 +1,29 @@
+---
+title: "Interlinks Example"
+filters:
+  - interlinks.py
+interlinks:
+  sources:
+    siuba:
+      url: https://siuba.org/
+      inv: null
+      fallback: objects_siuba.json
+    vetiver:
+      url: https://vetiver.rstudio.com/
+      inv: null
+      fallback: objects_vetiver.json
+---
+
+## Heading {#sec-hello}
+
+## Testing
+
+
+| style | syntax | output |
+| ----- | ------ | ------ |
+| md custom text  | `[some explanation](`vetiver.SKLearnHandler`)` | [some explanation](`vetiver.SKLearnHandler`) |
+| md blank text   | `[](`vetiver.SKLearnHandler`)` | [](`vetiver.SKLearnHandler`) |
+| md blank text (~shortened)| `[](`~vetiver.SKLearnHandler`)` | [](`~vetiver.SKLearnHandler`) |
+| rst custom text | `` :ref:`some explanation <vetiver.SKLearnHandler>` `` | :ref:`some explanation <vetiver.SKLearnHandler>` |
+| rst blank text  | `` :ref:`vetiver.SKLearnHandler` `` | :ref:`vetiver.SKLearnHandler` |
+| rst blank text (~shortened) | `` :ref:`~vetiver.SKLearnHandler` `` | :ref:`~vetiver.SKLearnHandler` |