Merge pull request #3 from rstudio/docs-quarto

docs: basic quarto api docs
posit-dev · Sep 28, 2023 · 43ac235 · 43ac235
2 parents 33f84c9 + ab0b22d
commit 43ac235
Show file tree

Hide file tree

Showing 19 changed files with 216 additions and 115 deletions.
diff --git a/.github/workflows/ci-docs.yaml b/.github/workflows/ci-docs.yaml
@@ -0,0 +1,82 @@
+on:
+    push:
+      branches:
+        - main
+    pull_request:
+      branches:
+        - main
+
+name: CI Docs
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v2
+        with:
+          python-version: "3.10"
+      - name: Install dependencies
+        run: |
+          python -m pip install ".[dev]"
+      - uses: quarto-dev/quarto-actions/setup@v2
+      - name: Build docs
+        run: |
+          make docs-build
+      # push to netlify -------------------------------------------------------
+
+      # set release name ----
+
+      - name: Configure pull release name
+        if: ${{github.event_name == 'pull_request'}}
+        run: |
+          echo "RELEASE_NAME=pr-${PR_NUMBER}" >> $GITHUB_ENV
+        env:
+          PR_NUMBER: ${{ github.event.number }}
+      - name: Configure branch release name
+        if: ${{github.event_name != 'pull_request'}}
+        run: |
+          # use branch name, but replace slashes. E.g. feat/a -> feat-a
+          echo "RELEASE_NAME=${GITHUB_REF_NAME/\//-}" >> $GITHUB_ENV
+      # deploy ----
+
+      - name: Create Github Deployment
+        uses: bobheadxi/deployments@v0.4.3
+        id: deployment
+        with:
+          step: start
+          token: ${{ secrets.GITHUB_TOKEN }}
+          env: ${{ env.RELEASE_NAME }}
+          ref: ${{ github.head_ref }}
+          transient: true
+          logs: 'https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}'
+
+      - name: Netlify docs preview
+        run: |
+          npm install -g netlify-cli
+          # push main branch to production, others to preview --
+          if [ "${ALIAS}" == "main" ]; then
+            netlify deploy --dir=docs/_site --alias="main"
+          else
+            netlify deploy --dir=docs/_site --alias="${ALIAS}"
+          fi
+        env:
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          ALIAS: ${{ steps.deployment.outputs.env }}
+
+      - name: Update Github Deployment
+        uses: bobheadxi/deployments@v0.4.3
+        if: ${{ always() }}
+        with:
+          step: finish
+          token: ${{ secrets.GITHUB_TOKEN }}
+          status: ${{ job.status }}
+          deployment_id: ${{ steps.deployment.outputs.deployment_id }}
+          env_url: 'https://${{ steps.deployment.outputs.env }}--gt-python.netlify.app'
+          logs: 'https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}'
+      - uses: peaceiris/actions-gh-pages@v3
+        if: github.event_name == 'release'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/_site
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1 @@
+I am the changelog
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1 +1,2 @@
 include gt/css/*.scss
+include gt/data/*.csv
diff --git a/Makefile b/Makefile
@@ -35,5 +35,10 @@ dist: clean ## builds source and wheel package
 	python3 setup.py bdist_wheel
 	ls -l dist
 
+docs-build:
+	cd docs \
+	  && quartodoc build --verbose \
+	  && quarto render
+
 install: dist ## install the package to the active Python's site-packages
-	python3 -m pip install --force-reinstall dist/gt*.whl
+	python3 -m pip install --force-reinstall dist/gt*.whl
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,7 @@
+/.quarto/
+
+# quartodoc
+_site
+_sidebar.yml
+objects.json
+reference
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/_quarto.yml b/docs/_quarto.yml
@@ -0,0 +1,102 @@
+project:
+  type: website
+
+
+website:
+  title: gt
+  page-navigation: true
+  navbar:
+    left:
+      - href: articles/intro.qmd
+      - text: Articles
+        menu:
+          - articles/case-study-gtcars.qmd
+      - href: reference/index.qmd
+      - href: changelog.qmd
+    right:
+      - icon: github
+        href: https://github.com/rstudio/gt-python/
+
+
+format:
+  html:
+    theme: cosmo
+    # css: styles.css
+    toc: true
+
+
+# tell quarto to read the generated sidebar
+metadata-files:
+  - _sidebar.yml
+
+
+quartodoc:
+  # the name used to import the package
+  package: gt
+
+  # write sidebar data to this file
+  sidebar: _sidebar.yml
+  dynamic: true
+
+  sections:
+    - title: Table Creation
+      contents:
+        - GT
+        # TODO: not sure where this function is
+        # - gt_preview
+    - title: Creating or modifying parts of a table
+      contents:
+        - GT.tab_header
+        - GT.tab_options
+        - GT.tab_source_note
+        - GT.tab_stubhead
+    - title: Formatting column data
+      contents:
+        - GT.fmt_engineering
+        - GT.fmt_integer
+        - GT.fmt_number
+        - GT.fmt_percent
+        - GT.fmt_scientific
+        - GT.fmt
+    - title: Text transformation
+    - title: Modifying columns
+      contents:
+        - GT.cols_label
+    - title: Adding or modifying rows
+    - title: Removing parts of a table
+    - title: Helper functions
+      contents:
+        - md
+        - html
+        - px
+        - pct
+        # - from_column
+        # - currency
+        # - nanoplot_options
+        # - adjust_luminance
+    - title: Image addition utilities
+    - title: Table options
+      contents:
+        - GT.opt_align_table_header
+        - GT.opt_all_caps
+        - GT.opt_footnote_marks
+        - GT.opt_row_striping
+    - title: Informational tables for reference
+    - title: Shiny
+    - title: Export and extraction functions
+    - title: Working with table groups
+    - title: Vector formatting
+    - title: Built in datasets
+      contents:
+        - data.countrypops
+        - data.sza
+        - data.gtcars
+        - data.sp500
+        - data.pizzaplace
+        - data.exibble
+        # - data.towny
+        # - data.metro
+        # - data.illness
+        # - data.rx_adsl
+        # - data.rx_addv
+
diff --git a/docs/articles/case-study-gtcars.qmd b/docs/articles/case-study-gtcars.qmd
@@ -0,0 +1,3 @@
+---
+title: "Case Study: gtcars"
+---
diff --git a/docs/articles/intro.qmd b/docs/articles/intro.qmd
@@ -0,0 +1,3 @@
+--- 
+title: Intro
+---
diff --git a/docs/changelog.md b/docs/changelog.md
diff --git a/docs/changelog.qmd b/docs/changelog.qmd
@@ -0,0 +1,5 @@
+---
+title: Changelog
+---
+
+{{< include ../CHANGELOG.md >}}
diff --git a/docs/conduct.md b/docs/conduct.md
diff --git a/docs/conf.py b/docs/conf.py
diff --git a/docs/contributing.md b/docs/contributing.md
diff --git a/docs/index.md b/docs/index.md
diff --git a/docs/make.bat b/docs/make.bat
diff --git a/docs/requirements.txt b/docs/requirements.txt
diff --git a/gt/__init__.py b/gt/__init__.py
@@ -1,6 +1,6 @@
 __version__ = "0.0.1"
 
-from .gt import *
+from .gt import GT
 from ._base_api import *
 from ._body import *
 from ._boxhead import *

diff --git a/setup.cfg b/setup.cfg
@@ -48,5 +48,10 @@ tests_require =
     pytest>=3
 zip_safe = False
 
+[options.extras_require]
+dev =
+    quartodoc
+    pytest
+
 [flake8]
 exclude = docs, .venv