Update function descriptions within components files

.github/workflows/deploy-docs.yml

@@ -6,21 +6,24 @@ on:
   pull_request:
     branches: [main]
 
+# Limit actions on PRs to a single job
+concurrency:
+  group: ${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: ["3.10"]
-      fail-fast: false
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
 
-      - name: Set up Python ${{ matrix.python-version }}
+      - name: Set up Python 3.10
         uses: actions/setup-python@v4
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: "3.10"
 
       - name: Upgrade pip
         run: python -m pip install --upgrade pip
@@ -46,15 +49,72 @@ jobs:
           make deps
 
       # =====================================================
-      # Build
+      # Setup site
       # =====================================================
       - uses: quarto-dev/quarto-actions/setup@v2
         with:
           version: 1.3.340
 
+      - name: Create quartodoc artifacts
+        run: |
+          make quartodoc
+
+      # =====================================================
+      # Notify PR of file updates
+      # =====================================================
+
+      - name: Find updates to components
+        if: ${{github.event_name == 'pull_request'}}
+        id: components
+        shell: bash
+        run: |
+          git diff --quiet -- components && exit 0
+          # Changes detected
+          echo "has-changes=true" >> "$GITHUB_OUTPUT"
+          # Output changes
+          echo "Changed files:"
+          git diff --name-only
+      - name: Push back component updates to repo
+        uses: stefanzweifel/git-auto-commit-action@v5
+        if: |
+          github.event_name == 'pull_request' &&
+          (! github.event.pull_request.head.repo.fork) &&
+          steps.components.outputs.has-changes == 'true'
+        with:
+          commit_message: "`make quartodoc` (GitHub Actions)"
+          file_pattern: components
+
+      - name: Write comment to update components folder
+        if: |
+          github.event_name == 'pull_request' &&
+          github.event.pull_request.head.repo.fork &&
+          steps.components.outputs.has-changes == 'true'
+        uses: thollander/actions-comment-pull-request@v2
+        with:
+          message: |
+            Please call `make quartodoc` to update files within the components folder
+
+            - [ ] Call `make quartodoc` in terminal
+            - [ ] Commit & push changes
+          comment_tag: make_quartodoc
+      - name: Remove comment to update components folder
+        if: |
+          github.event_name == 'pull_request' &&
+          github.event.pull_request.head.repo.fork &&
+          steps.components.outputs.has-changes != 'true'
+        uses: thollander/actions-comment-pull-request@v2
+        with:
+          # message: |
+          #   Components folder is up to date. Removing comment
+          comment_tag: make_quartodoc
+          mode: delete
+
+      # =====================================================
+      # Build
+      # =====================================================
       - name: Build site
         run: |
-          make all
+          make site
 
       # =====================================================
       # Deploy docs to Netlify

Makefile

@@ -70,13 +70,15 @@ deps: $(PYBIN)
 	cd py-shiny/docs && make deps
 
 ## Build qmd files for Shiny API docs
-quartodoc:
+quartodoc: $(PYBIN)
 	cd py-shiny/docs && make quartodoc
 	# Copy all generated files except index.qmd
 	rsync -av --exclude="index.qmd" py-shiny/docs/api/ ./api
 	cp -R py-shiny/docs/_inv py-shiny/docs/objects.json ./
 	# Copy over index.qmd, but rename it to _api_index.qmd
 	cp py-shiny/docs/api/index.qmd ./api/_api_index.qmd
+	. $(PYBIN)/activate && python scripts/_add_objects_func_info.py
+	. $(PYBIN)/activate && python scripts/post-quartodoc.py
 
 ## Build website
 site:

components/display-messages/modal.qmd

@@ -1,6 +1,6 @@
 ---
-title: "Modal"
-sidebar: components 
+title: Modal
+sidebar: components
 previewapp: |
   from shiny import App, Inputs, Outputs, Session, reactive, ui
 
@@ -29,11 +29,11 @@ listing:
         preview: https://shinylive.io/py/app/#h=0&code=NobwRAdghgtgpmAXGKAHVA6VBPMAaMAYwHsIAXOcpMAMwCdiYACAZwAsBLCbJjmVYnTJMAgujxM6cKITIcAbnAkBXDgB0IGtKgD6qpgF4mqrFADmcHTQA2qgCYAKDUxfGOGLqmVkdMuaR0AI28yUicwdmIAdzV8JliAZTZophhiOyhrJjsOTOIzWIBKPA1CjQ07OBpWODpFOgdPbwliby8yCRY4FhYOUkLEZ1cAASk-BTgMAFEaGjhZIZdR6VkJjDhFckaIdoxIqLKIV2yqph0HAcXj1MM3DDSM6ycj69fYgBVOFl5vqFZGOBRNhQYR8ARCKDkVLdFjmSaxEovV7HORkaxwAyJAFAkG8fiCMiQ4TwHpwhFXZFMaQsbA6QjWYhdAzvOjKJQU5E0YjECh0AwmB6ZIIhMKxAAiHBYMElLCKiMph0pAvSQv2Dhghy06FuYlQDm0eg4nVq9UKYAAvgBdIA
         code: |
           from shiny import App, reactive, ui
-          
+
           app_ui = ui.page_fluid(
               ui.input_action_button("show", "Show modal dialog"),
           )
-          
+
           def server(input, output, session):
               @reactive.Effect
               @reactive.event(input.show)
@@ -44,21 +44,25 @@ listing:
                       easy_close=True #<<
                   ) #<<
                   ui.modal_show(m) #<<
-          
+
           app = App(app_ui, server)
         relevantfunctions:
-          - title: "ui.modal"
-            href: https://shiny.posit.co/py/api/ui.modal.html
-            signature: ui.modal(*args, title=None, footer=MISSING, size='m', easy_close=False, fade=True, **kwargs)
-          - title: "ui.modal_show"
-            href: https://shiny.posit.co/py/api/ui.modal_show.html
-            signature: ui.modal_show(modal, session=None)
-          - title: "ui.modal_remove"
-            href: https://shiny.posit.co/py/api/ui.modal_remove.html
-            signature: ui.modal_remove(session=None)
-          - title: "ui.modal_button"
-            href: https://shiny.posit.co/py/api/ui.modal_button.html
-            signature: ui.modal_button(label, icon=None, **kwargs)
+          - title: ui.modal
+            href: https://shiny.posit.co/py/api/ui.modal.html#shiny.ui.modal
+            signature: "ui.modal(*args: TagChild | TagAttrs = (), title: Optional = None, footer: TagChild | MISSING_TYPE = MISSING, size: Literal = 'm', easy_close: bool = False, fade: bool = True, **kwargs: TagAttrValue = {})"
+            github: https://github.com/posit-dev/py-shiny/blob/a0df2ed/shiny/ui/_modal.py#L60-L156
+          - title: ui.modal_show
+            href: https://shiny.posit.co/py/api/ui.modal_show.html#shiny.ui.modal_show
+            signature: 'ui.modal_show(modal: Tag, session: Optional = None)'
+            github: https://github.com/posit-dev/py-shiny/blob/a0df2ed/shiny/ui/_modal.py#L159-L185
+          - title: ui.modal_remove
+            href: https://shiny.posit.co/py/api/ui.modal_remove.html#shiny.ui.modal_remove
+            signature: 'ui.modal_remove(session: Optional = None)'
+            github: https://github.com/posit-dev/py-shiny/blob/a0df2ed/shiny/ui/_modal.py#L188-L212
+          - title: ui.modal_button
+            href: https://shiny.posit.co/py/api/ui.modal_button.html#shiny.ui.modal_button
+            signature: 'ui.modal_button(label: TagChild, icon: TagChild = None, **kwargs: TagAttrValue = {})'
+            github: https://github.com/posit-dev/py-shiny/blob/a0df2ed/shiny/ui/_modal.py#L19-L57
   - id: variations
     template: ../_partials/components-variations.ejs
     contents:
@@ -68,11 +72,11 @@ listing:
           preview: https://shinylive.io/py/app/#h=0&code=NobwRAdghgtgpmAXGKAHVA6VBPMAaMAYwHsIAXOcpMAMwCdiYACAZwAsBLCbJjmVYnTJMAgujxM6cKITIcAbnAkBXDgB0IGtKgD6qpgF4mqrFADmcHTQA2qgCYAKDUxfGOGLqmVkdMuaR0AI28yUicwa2IzLjV8JliAGSiYsABKPA1UjQ07OBpWODpFOgdPbwliby8yCRY4FhYOUlTEZ1cAASk-BTgMAFEaGjhZNpdO6VkejDhFclKIaoxI6IgsiFcmXPydBxbRjaZmIxMYYjsoayd1g5uTMp8KAA8ycOh4WIlYgFU6uje4VppDLXG4bO4Lbw6VBQBoAd0Ejli0LhCI+8TAAAUYSx4XQ7ID0vtQW4PBCfN0AsEyKEIOESBAIMMyGjYgBhUiMkZAomg6QsbA6QiROoGAAqdGUSh5NxoxGIFDoBgAcqQ4NKmGtiSczhcdOxiLCHDBNaD9uNuop+oMmWaupNLTNKC97hh6ZyyCaXFsmDodnsQQdtedrDopKdFLt1QBiJjs3JMUJMN1MpiwjhkNi8MkYf67JhQCB2LOLZE4hGRzTQdCGUToBzaPQcWqFYqpMAAXwAukA
           code: |
             from shiny import App, reactive, ui
-            
+
             app_ui = ui.page_fluid(
                 ui.input_action_button("login", "Login"),
             )
-            
+
             def server(input, output, session):
                 @reactive.Effect
                 @reactive.event(input.login)
@@ -91,7 +95,7 @@ listing:
                 def __(): #<<
                     ui.modal_remove() #<<
                     # Code to connect with input.name() and input.password() #<<
-            
+
             app = App(app_ui, server)
 ---
 

components/display-messages/notifications.qmd

@@ -1,5 +1,5 @@
 ---
-title: "Notifications / Help Text"
+title: Notifications / Help Text
 sidebar: components
 previewapp: |
   from shiny import App, reactive, ui
@@ -64,11 +64,13 @@ listing:
           app = App(app_ui, server)
         relevantfunctions:
           - title: ui.notification_show
-            href: https://shiny.posit.co/py/api/ui.notification_show.html
-            signature: ui.notification_show(ui, *, action=None, duration=5, close_button=True, id=None, type='default', session=None)
+            href: https://shiny.posit.co/py/api/ui.notification_show.html#shiny.ui.notification_show
+            signature: "ui.notification_show(ui: TagChild, action: Optional = None, duration: Optional = 5, close_button: bool = True, id: Optional = None, type: Literal = 'default', session: Optional = None)"
+            github: https://github.com/posit-dev/py-shiny/blob/a0df2ed/shiny/ui/_notification.py#L14-L90
           - title: ui.notification_remove
-            href: https://shiny.posit.co/py/api/ui.notification_remove.html
-            signature: ui.notification_remove(id, *, session=None)
+            href: https://shiny.posit.co/py/api/ui.notification_remove.html#shiny.ui.notification_remove
+            signature: 'ui.notification_remove(id: str, session: Optional = None)'
+            github: https://github.com/posit-dev/py-shiny/blob/a0df2ed/shiny/ui/_notification.py#L93-L125
   - id: variations
     template: ../_partials/components-variations.ejs
     contents:
@@ -180,7 +182,7 @@ listing:
             app = App(app_ui, server)
 
         - title: Help Text
-          description: "[`ui.help_text()`](https://shiny.posit.co/py/api/ui.help_text.html) creates stylized help text which can be added to the user interface to provide additional explanation or context. [Tooltips](tooltips.qmd) provides a similar, but alternative way to display information to the user."
+          description: '[`ui.help_text()`](https://shiny.posit.co/py/api/ui.help_text.html) creates stylized help text which can be added to the user interface to provide additional explanation or context. [Tooltips](tooltips.qmd) provides a similar, but alternative way to display information to the user.'
           preview: https://shinylive.io/py/app/#h=0&code=NobwRAdghgtgpmAXGKAHVA6VBPMAaMAYwHsIAXOcpMAMwCdiYACAZwAsBLCbJjmVYnTJMAgujxM6cKITIcAbnAkBXDgB0IGtKgD6qpgF4mqrFADmcHTQA2qgCYAKDUxfGOGLqmVkdMuaR0AI28yUicwdmIAdzV8JliAZTZopgA5YjkaDkIof00wAEo8Z1cTT29fWQ4A4LJQiHCpGGJFWIlYgCU4ZsU0jI4snLzYoo0CjQ07OBpWODpFOgdysgliby8V2ZYWaogCxBKXDjsWRCZrDhYyYCu6AF1DJmA7w6YIM65hIwAGCYhXJgAASkfgUcAwAFEaDQ4LJXsDpFVFBg4IpyEsIBsMJEouN-q4pjMdA59q8ARBSNZiDlrLwTmTXBSIFSaW8GS4AMRMBJQXpkNhwJgASQAIkwaIJJN0WlBadZcnN2XTHiYKZlsrldjoceEALJwbbmQWxJgAalYZEWewkdmUdE1pAM6QgcDxAIBxxYGG0lEcxzd7pc-1NRgAjH8AQjQcioTC4fiXFGkeDUZQyBisU0Wq7XoSmMTSQn3UyWbK6SwlQNywci4GXKr+oMHRAdFnFEsTlhiKgSXitOhHmIe9o9BwJCw5gsCmAAL53IA
           height: 200px
           code: |

components/display-messages/progress-bar.qmd

@@ -1,6 +1,6 @@
 ---
-title: "Progress Bar"
-sidebar: components 
+title: Progress Bar
+sidebar: components
 previewapp: |
   import asyncio
 
@@ -33,50 +33,51 @@ previewapp: |
   ## file: styles.css
   #shiny-notification-panel { max-width: 100%; }
 listing:
-  id: component
-  template: ../_partials/components-detail.ejs
-  contents:
-    - title: Progress Bar
-      preview: https://shinylive.io/py/app/#h=0&code=NobwRAdghgtgpmAXGKAHVA6VBPMAaMAYwHsIAXOcpMASxlWICcyACKAZ2wkJuIB0IAgGaNiMFuwAWNCNhZ0GzFgEF0eFozhRCZGgDc46zRAAmcRuoCuNAQLSoA+tZYBeFtaxQA5nAdCANtYmABQCLOHuNBgyqJZkDtq6pA4ARnFkpKFgaWQZgvgsfGAAwmKxFEUAlHhhER7EceUOFAAeZFkk9HFwVTUQlbamcEIS5gaMwTFx6g1k5erscOzsvP2IteEAArPlGyybxmaMGK1kewdaOvpwGHAG5JMQ5Rg5eQMQEWyc3CxmI53lODBSrrD6fCIAdxoZEkkQwAAVRF5NMtgjAZC4AIzqGBQFpYgCslS+LFQoPBFNJGEW7Xgy28cBcRWKUH8hEs-igSQ+MlJSJR7CK6jMZCgNH8TLAABVpOwWLi5KKANZwNgsCHSfw3DAYKqDSngoRMeTyD6MKAQHzBbEsTFE8kGymYGmTHFLdgMyWlLq6S16sGO8FQCFi1gcLg8YjUrVwVDBAAMGEx7z2n00ZEsjA+RQAIqRVQC4jIvABCIqDeyuFToYL2Jw0BZjcyVMAAXwAukA
-      height: 200px
-      code: |
-        import asyncio
-
-        from shiny import App, reactive, render, ui
-
-        app_ui = ui.page_fluid(
-            ui.input_action_button("button", "Compute"),
-            ui.output_text("compute"),
-        )
-
-        def server(input, output, session):
-            @output
-            @render.text
-            @reactive.event(input.button)
-            async def compute():
-                with ui.Progress(min=1, max=15) as p:
-                    p.set(message="Calculation in progress", detail="This may take a while...")
-
-                    for i in range(1, 15):
-                        p.set(i, message="Computing")
-                        await asyncio.sleep(0.1)
-
-                return "Done computing!"
-
-        app = App(app_ui, server)
-      relevantfunctions:
-        - title: "ui.Progress"
-          href: https://shiny.posit.co/py/api/ui.Progress.html
-          signature: ui.Progress(self, min=0, max=1, session=None)
-        - title: "ui.Progress.close"
-          href: https://shiny.posit.co/py/api/ui.Progress.html
-          signature: ui.Progress.close(self)
-        - title: "ui.Progress.inc"
-          href: https://shiny.posit.co/py/api/ui.Progress.html
-          signature: ui.Progress.inc(self, amount=0.1, message=None, detail=None)
-        - title: "ui.Progress.set"
-          href: https://shiny.posit.co/py/api/ui.Progress.html
-          signature: ui.Progress.set(self, value=None, message=None, detail=None)
+  - id: component
+    template: ../_partials/components-detail.ejs
+    contents:
+      - title: Progress Bar
+        preview: https://shinylive.io/py/app/#h=0&code=NobwRAdghgtgpmAXGKAHVA6VBPMAaMAYwHsIAXOcpMASxlWICcyACKAZ2wkJuIB0IAgGaNiMFuwAWNCNhZ0GzFgEF0eFozhRCZGgDc46zRAAmcRuoCuNAQLSoA+tZYBeFtaxQA5nAdCANtYmABQCLOHuNBgyqJZkDtq6pA4ARnFkpKFgaWQZgvgsfGAAwmKxFEUAlHhhER7EceUOFAAeZFkk9HFwVTUQlbamcEIS5gaMwTFx6g1k5erscOzsvP2IteEAArPlGyybxmaMGK1kewdaOvpwGHAG5JMQ5Rg5eQMQEWyc3CxmI53lODBSrrD6fCIAdxoZEkkQwAAVRF5NMtgjAZC4AIzqGBQFpYgCslS+LFQoPBFNJGEW7Xgy28cBcRWKUH8hEs-igSQ+MlJSJR7CK6jMZCgNH8TLAABVpOwWLi5KKANZwNgsCHSfw3DAYKqDSngoRMeTyD6MKAQHzBbEsTFE8kGymYGmTHFLdgMyWlLq6S16sGO8FQCFi1gcLg8YjUrVwVDBAAMGEx7z2n00ZEsjA+RQAIqRVQC4jIvABCIqDeyuFToYL2Jw0BZjcyVMAAXwAukA
+        height: 200px
+        code: |
+          import asyncio
+
+          from shiny import App, reactive, render, ui
+
+          app_ui = ui.page_fluid(
+              ui.input_action_button("button", "Compute"),
+              ui.output_text("compute"),
+          )
+
+          def server(input, output, session):
+              @output
+              @render.text
+              @reactive.event(input.button)
+              async def compute():
+                  with ui.Progress(min=1, max=15) as p:
+                      p.set(message="Calculation in progress", detail="This may take a while...")
+
+                      for i in range(1, 15):
+                          p.set(i, message="Computing")
+                          await asyncio.sleep(0.1)
+
+                  return "Done computing!"
+
+          app = App(app_ui, server)
+        relevantfunctions:
+          - title: ui.Progress
+            href: https://shiny.posit.co/py/api/ui.Progress.html#shiny.ui.Progress
+            signature: 'ui.Progress(min: int = 0, max: int = 1, session: Optional = None)'
+            github: https://github.com/posit-dev/py-shiny/blob/a0df2ed/shiny/ui/_progress.py#L14-L167
+          - title: ui.Progress.close
+            href: https://shiny.posit.co/py/api/ui.Progress.html
+            signature: ui.Progress.close(self)
+          - title: ui.Progress.inc
+            href: https://shiny.posit.co/py/api/ui.Progress.html
+            signature: ui.Progress.inc(self, amount=0.1, message=None, detail=None)
+          - title: ui.Progress.set
+            href: https://shiny.posit.co/py/api/ui.Progress.html
+            signature: ui.Progress.set(self, value=None, message=None, detail=None)
 
 ---