Automatically make documentation pages for Docassemble Interviews

.github/workflows/deploy.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Clear pip cache
         run: |
           pip cache purge
-      - run: pip install docspec_python==2.2.1 git+https://github.com/nonprofittechy/pydoc-markdown@escape-brackets
+      - run: pip install ruamel.yaml docspec_python==2.2.1 git+https://github.com/nonprofittechy/pydoc-markdown@escape-brackets
       - uses: actions/checkout@v3
         with:
           path: docs
@@ -46,6 +46,7 @@ jobs:
         run: |
           cd docs
           pydoc-markdown
+          ./make_interview_docs.py ../docassemble-ALDashboard
           ./fix-doc-titles.sh
       - uses: actions/setup-node@v3
         with:

.github/workflows/test-deploy.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Clear pip cache
         run: |
           pip cache purge
-      - run: pip install docspec_python==2.2.1 git+https://github.com/nonprofittechy/pydoc-markdown@escape-brackets
+      - run: pip install ruamel.yaml docspec_python==2.2.1 git+https://github.com/nonprofittechy/pydoc-markdown@escape-brackets
       - uses: actions/checkout@v3
         with:
           path: docs
@@ -46,6 +46,7 @@ jobs:
         run: |
           cd docs
           pydoc-markdown
+          ./make_interview_docs.py ../docassemble-ALDashboard
           ./fix-doc-titles.sh
       - uses: actions/setup-node@v3
         with:

docs/interviews/ALDashboard/api_test.md

@@ -0,0 +1,14 @@
+# API Tester
+
+This interview lets you easily test various APIs that docassemble uses, including:
+
+* [Google Maps geocoding](https://docassemble.org/docs/config.html#geocoder%20service)
+* [Email sending](https://docassemble.org/docs/config.html#mail)
+* [SMS sending](https://docassemble.org/docs/sms.html#sms%20setup)
+* [LLM Chat Completion](https://assemblyline.suffolklitlab.org/docs/components/ALToolbox/llms#ALToolbox.llms.chat_completion)
+
+You will need to have those APIs setup in your docassemble configuration. Instructions on how to
+do so are linked above for each API.
+
+
+See it [in action](https://apps-dev.suffolklitlab.org//start/ALDashboard/api_test).

docs/interviews/ALDashboard/browse_interviews.md

@@ -0,0 +1,18 @@
+# Browse Interviews
+
+This interview allows you to list all YAML files on the system, which may reveal
+a new attack surface if you do not properly secure sensitive interviews.
+
+By default it can be accessed by developers or admins on production servers,
+and by any logged in user on a development server (with debug: True in global config).
+
+If you would like to limit access without turning off "debug" mode, modify the global
+configuration as follows:
+
+```yaml
+assembly line:
+  require login to browse interviews on development servers: True
+```
+
+
+See it [in action](https://apps-dev.suffolklitlab.org//start/ALDashboard/browse_interviews).

make_interview_docs.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+
+"""
+Run this to generate documentation pages from Docassemble interview files directly,
+like we use pydoc to generate docs from .py files.
+
+Currently, just grabs the comment in a `id: interview documentation` block, assumes
+it's markdown, and puts it in a markdown file with a direct link to the interview
+on the dev server. If no such block exists, no documentation is generated.
+"""
+
+from ruamel.yaml import YAML
+import sys
+import glob
+from pathlib import Path
+
+yaml = YAML(typ='safe', pure=True)
+
+DEV_SERVER = "https://apps-dev.suffolklitlab.org/"
+
+def generate_docs_from_yaml_file(file, component):
+    new_file = Path(f"docs/interviews/{component}/{file.stem}.md")
+    with open(file, 'r') as f:
+        first_block = next(yaml.load_all(f), None)
+        if first_block and "comment" in first_block:
+            new_file.parent.mkdir(parents=True, exist_ok=True)
+            with open(new_file, 'w') as new_f:
+                new_f.write(first_block['comment'])
+                new_f.write(f"\n\nSee it [in action]({DEV_SERVER}/start/{component}/{file.stem}).");
+
+def main(args):
+    if not args:
+        print("Generated no docs")
+    for dir in args:
+        component_name = Path(dir).stem.split("-")[-1].strip("/")
+        for file in glob.glob(f"{dir}/docassemble/*/data/questions/*.yml"):
+            generate_docs_from_yaml_file(Path(file), component_name)
+
+if __name__ == '__main__':
+    main(sys.argv[1:])

sidebars.js

@@ -222,6 +222,10 @@ module.exports = {
         'components/GithubFeedbackForm/githubfeedbackform_overview',
         'components/InterviewStats/interviewstats_overview',
         'components/ALDashboard/aldashboard_overview',
+        {
+            type: 'autogenerated',
+            dirName: 'interviews'
+        },
         {
             label: 'ALDashboard modules',
             type: 'category',