diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 0e858642c..f59ecd6c4 100644 --- a/.github/workflows/deploy.yml +++ b/.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: diff --git a/.github/workflows/test-deploy.yml b/.github/workflows/test-deploy.yml index dc9f14f8a..f5e2f5ac6 100644 --- a/.github/workflows/test-deploy.yml +++ b/.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: diff --git a/docs/interviews/ALDashboard/api_test.md b/docs/interviews/ALDashboard/api_test.md new file mode 100644 index 000000000..a697cdc22 --- /dev/null +++ b/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). \ No newline at end of file diff --git a/docs/interviews/ALDashboard/browse_interviews.md b/docs/interviews/ALDashboard/browse_interviews.md new file mode 100644 index 000000000..372db80c3 --- /dev/null +++ b/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). \ No newline at end of file diff --git a/make_interview_docs.py b/make_interview_docs.py new file mode 100755 index 000000000..189a4f226 --- /dev/null +++ b/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:]) diff --git a/sidebars.js b/sidebars.js index 54ac6bb1c..e4c5c5009 100644 --- a/sidebars.js +++ b/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',