Skip to content

Commit 306620a

Browse files
nonprofittechynonprofittechy
authored
Merge pull request #564 from SuffolkLITLab/copilot/fix-563
Add ALDashboard to auto-documentation generation system
2 parents f221a96 + 53d6b2e commit 306620a

22 files changed

+2182
-133
lines changed

‎.github/workflows/deploy.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,10 @@ jobs:
3838
with:
3939
repository: SuffolkLITLab/docassemble-EFSPIntegration
4040
path: docassemble-EFSPIntegration
41+
- uses: actions/checkout@v3
42+
with:
43+
repository: SuffolkLITLab/docassemble-ALDashboard
44+
path: docassemble-ALDashboard
4145
- name: Go to Docs directory
4246
run: |
4347
cd docs

‎.github/workflows/test-deploy.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,10 @@ jobs:
3838
with:
3939
repository: SuffolkLITLab/docassemble-EFSPIntegration
4040
path: docassemble-EFSPIntegration
41+
- uses: actions/checkout@v3
42+
with:
43+
repository: SuffolkLITLab/docassemble-ALDashboard
44+
path: docassemble-ALDashboard
4145
- name: Go to Docs directory
4246
run: |
4347
cd docs

‎docs/components/ALDashboard/aldashboard.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Table of Contents
2+
3+
* [ALDashboard.aldashboard](#ALDashboard.aldashboard)
4+
* [speedy\_get\_users](#ALDashboard.aldashboard.speedy_get_users)
5+
* [speedy\_get\_sessions](#ALDashboard.aldashboard.speedy_get_sessions)
6+
* [dashboard\_get\_session\_variables](#ALDashboard.aldashboard.dashboard_get_session_variables)
7+
* [ALPackageInstaller](#ALDashboard.aldashboard.ALPackageInstaller)
8+
* [get\_validated\_github\_username](#ALDashboard.aldashboard.ALPackageInstaller.get_validated_github_username)
9+
* [ErrorList](#ALDashboard.aldashboard.ErrorList)
10+
* [ErrorLikeObject](#ALDashboard.aldashboard.ErrorLikeObject)
11+
* [install\_fonts](#ALDashboard.aldashboard.install_fonts)
12+
* [list\_installed\_fonts](#ALDashboard.aldashboard.list_installed_fonts)
13+
* [nicer\_interview\_filename](#ALDashboard.aldashboard.nicer_interview_filename)
14+
* [list\_question\_files\_in\_package](#ALDashboard.aldashboard.list_question_files_in_package)
15+
* [list\_question\_files\_in\_docassemble\_packages](#ALDashboard.aldashboard.list_question_files_in_docassemble_packages)
16+
17+
---
18+
sidebar_label: aldashboard
19+
title: ALDashboard.aldashboard
20+
---
21+
22+
<a id="ALDashboard.aldashboard.speedy_get_users"></a>
23+
24+
#### speedy\_get\_users()
25+
26+
```python
27+
def speedy_get_users() -> List[Dict[int, str]]
28+
```
29+
30+
Return a list of all users in the database. Possibly faster than get_user_list().
31+
32+
<a id="ALDashboard.aldashboard.speedy_get_sessions"></a>
33+
34+
#### speedy\_get\_sessions(user\_id: Optional[int] = None, filename: Optional[str] = None, filter\_step1: bool = True, metadata\_key\_name: str = "metadata")
35+
36+
```python
37+
def speedy_get_sessions(user_id: Optional[int] = None,
38+
filename: Optional[str] = None,
39+
filter_step1: bool = True,
40+
metadata_key_name: str = "metadata") -> List[Tuple]
41+
```
42+
43+
Return a list of the most recent 500 sessions, optionally tied to a specific user ID.
44+
45+
Each session is a tuple with named columns:
46+
filename,
47+
user_id,
48+
modtime,
49+
key
50+
51+
<a id="ALDashboard.aldashboard.dashboard_get_session_variables"></a>
52+
53+
#### dashboard\_get\_session\_variables(session\_id: str, filename: str)
54+
55+
```python
56+
def dashboard_get_session_variables(session_id: str, filename: str)
57+
```
58+
59+
Return the variables and steps for a given session ID and YAML filename in serializable dictionary format.
60+
61+
<a id="ALDashboard.aldashboard.ALPackageInstaller"></a>
62+
63+
## ALPackageInstaller Objects
64+
65+
```python
66+
class ALPackageInstaller(DAObject)
67+
```
68+
69+
Methods and state for installing AssemblyLine.
70+
71+
<a id="ALDashboard.aldashboard.ALPackageInstaller.get_validated_github_username"></a>
72+
73+
#### get\_validated\_github\_username(access\_token: str)
74+
75+
```python
76+
def get_validated_github_username(access_token: str)
77+
```
78+
79+
Given a valid GitHub `access_token`, returns the username associated with it.
80+
Otherwise, adds one or more errors to the installer.
81+
82+
<a id="ALDashboard.aldashboard.ErrorList"></a>
83+
84+
## ErrorList Objects
85+
86+
```python
87+
class ErrorList(DAList)
88+
```
89+
90+
Contains `ErrorLikeObject`s so they can be recognized by docassemble.
91+
92+
<a id="ALDashboard.aldashboard.ErrorLikeObject"></a>
93+
94+
## ErrorLikeObject Objects
95+
96+
```python
97+
class ErrorLikeObject(DAObject)
98+
```
99+
100+
An object with a `template_name` that identifies the DALazyTemplate that will
101+
show its error. It can contain any other attributes so its template can access them
102+
as needed. DAObject doesn&#x27;t seem to be enough to allow template definition.
103+
104+
<a id="ALDashboard.aldashboard.install_fonts"></a>
105+
106+
#### install\_fonts(the\_font\_files: DAFileList)
107+
108+
```python
109+
def install_fonts(the_font_files: DAFileList)
110+
```
111+
112+
Install fonts to the server and restart both supervisor and unoconv.
113+
114+
<a id="ALDashboard.aldashboard.list_installed_fonts"></a>
115+
116+
#### list\_installed\_fonts()
117+
118+
```python
119+
def list_installed_fonts()
120+
```
121+
122+
List the fonts installed on the server.
123+
124+
<a id="ALDashboard.aldashboard.nicer_interview_filename"></a>
125+
126+
#### nicer\_interview\_filename(filename: str)
127+
128+
```python
129+
def nicer_interview_filename(filename: str) -> str
130+
```
131+
132+
Given a filename like docassemble.playground10ALWeaver:data/questions/assembly_line.yml,
133+
return a less cluttered name like: playground10ALWeaver:assembly_line
134+
135+
<a id="ALDashboard.aldashboard.list_question_files_in_package"></a>
136+
137+
#### list\_question\_files\_in\_package(package\_name: str)
138+
139+
```python
140+
def list_question_files_in_package(package_name: str) -> Optional[List[str]]
141+
```
142+
143+
List all the files in the &#x27;data/questions&#x27; directory of a package.
144+
145+
**Arguments**:
146+
147+
- `package_name` _str_ - The name of the package to list files from.
148+
149+
150+
**Returns**:
151+
152+
- `List[str]` - A list of filenames in the &#x27;data/questions&#x27; directory of the package.
153+
154+
<a id="ALDashboard.aldashboard.list_question_files_in_docassemble_packages"></a>
155+
156+
#### list\_question\_files\_in\_docassemble\_packages()
157+
158+
```python
159+
def list_question_files_in_docassemble_packages()
160+
```
161+
162+
List all the files in the &#x27;data/questions&#x27; directory of all docassemble packages.
163+
164+
**Returns**:
165+
166+
Dict[str, List[str]]: A dictionary where the keys are package names and the values are lists of filenames in the &#x27;data/questions&#x27; directory of the package.
167+

‎docs/components/ALDashboard/aldashboard_overview.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
id: aldashboard_overview
3+
title: ALDashboard overview
4+
sidebar_label: About ALDashboard
5+
slug: /components/ALDashboard/overview
6+
---
7+
8+
ALDashboard is a collection of tools to help administer a Docassemble server and debug interviews. It provides utilities for package management, server maintenance, translation workflows, and debugging tools specifically designed for the Document Assembly Line ecosystem.
9+
10+
:::warning This page is a stub
11+
12+
We have not yet documented the key modules in the ALDashboard.
13+
:::
14+
15+
## Main Modules
16+
17+
ALDashboard consists of several Python modules, each providing specific functionality:
18+
19+
- **aldashboard.py** - Core dashboard functionality and server management
20+
- **create_package.py** - Package creation and management utilities
21+
- **translation.py** - Translation workflow and management tools
22+
- **project_maintenance.py** - Project maintenance and update utilities
23+
- **docx_wrangling.py** - DOCX document processing and validation
24+
- **package_scanner.py** - Package analysis and scanning tools
25+
- **validate_docx.py** - DOCX validation utilities
26+
- **validate_attachment.py** - Attachment validation tools
27+
28+
Some of this functionality is useful outside of the ALDashboard. `project_maintenance.py` is specifically a tool to run from the commandline and is not available as a "widget" you can interact with from the Docassemble frontend.
29+
30+
## Installation
31+
32+
ALDashboard is typically installed as part of the Document Assembly Line setup:
33+
34+
- [Installation Guide](/docs/get_started/installation)

‎docs/components/ALDashboard/create_package.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Table of Contents
2+
3+
* [ALDashboard.create\_package](#ALDashboard.create_package)
4+
* [create\_package\_zip](#ALDashboard.create_package.create_package_zip)
5+
6+
---
7+
sidebar_label: create_package
8+
title: ALDashboard.create_package
9+
---
10+
11+
<a id="ALDashboard.create_package.create_package_zip"></a>
12+
13+
#### create\_package\_zip(pkgname: str, info: dict, author\_info: dict, folders\_and\_files: dict, fileobj: Optional[DAFile] = None)
14+
15+
```python
16+
def create_package_zip(pkgname: str,
17+
info: dict,
18+
author_info: dict,
19+
folders_and_files: dict,
20+
fileobj: Optional[DAFile] = None) -> DAFile
21+
```
22+
23+
Given a dictionary of lists, with the keys representing folders and the values
24+
representing a list of DAFiles, create a Python package with Docassemble conventions.
25+
info: (created by DAInterview.package_info())
26+
license
27+
author_name
28+
readme
29+
description
30+
url
31+
version
32+
dependencies
33+
// interview_files replaced with folders_and_files
34+
// template_files
35+
// module_files
36+
// static_files
37+
author_info:
38+
author name and email
39+
folders_and_files:
40+
questions-&gt;list of absolute file paths on the local filesystem
41+
templates
42+
modules
43+
static
44+
sources
45+
46+
Strucure of a docassemble package:
47+
+ docassemble-PKGNAME/
48+
LICENSE
49+
MANIFEST.in
50+
README.md
51+
setup.cfg
52+
setup.py
53+
+-------docassemble
54+
__init__.py
55+
+------PKGNAME
56+
__init__.py
57+
SOME_MODULE.py
58+
+------data
59+
+------questions
60+
README.md
61+
+------sources
62+
README.md
63+
+------static
64+
README.md
65+
+------templates
66+
README.md
67+

‎docs/components/ALDashboard/docx_wrangling.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Table of Contents
2+
3+
* [ALDashboard.docx\_wrangling](#ALDashboard.docx_wrangling)
4+
* [update\_docx](#ALDashboard.docx_wrangling.update_docx)
5+
* [get\_labeled\_docx\_runs](#ALDashboard.docx_wrangling.get_labeled_docx_runs)
6+
* [modify\_docx\_with\_openai\_guesses](#ALDashboard.docx_wrangling.modify_docx_with_openai_guesses)
7+
8+
---
9+
sidebar_label: docx_wrangling
10+
title: ALDashboard.docx_wrangling
11+
---
12+
13+
<a id="ALDashboard.docx_wrangling.update_docx"></a>
14+
15+
#### update\_docx(document: Union[docx.document.Document, str], modified\_runs: List[Tuple[int, int, str, int]])
16+
17+
```python
18+
def update_docx(
19+
document: Union[docx.document.Document, str],
20+
modified_runs: List[Tuple[int, int, str,
21+
int]]) -> docx.document.Document
22+
```
23+
24+
Update the document with modified runs.
25+
26+
**Arguments**:
27+
28+
- `document` - the docx.Document object, or the path to the DOCX file
29+
- `modified_runs` - a tuple of paragraph number, run number, the modified text, and
30+
a number from -1 to 1 indicating whether a new paragraph should be inserted
31+
before or after the current paragraph.
32+
33+
34+
**Returns**:
35+
36+
The modified document.
37+
38+
<a id="ALDashboard.docx_wrangling.get_labeled_docx_runs"></a>
39+
40+
#### get\_labeled\_docx\_runs(docx\_path: str, custom\_people\_names: Optional[Tuple[str, str]] = None, openai\_client: Optional[OpenAI] = None)
41+
42+
```python
43+
def get_labeled_docx_runs(
44+
docx_path: str,
45+
custom_people_names: Optional[Tuple[str, str]] = None,
46+
openai_client: Optional[OpenAI] = None
47+
) -> List[Tuple[int, int, str, int]]
48+
```
49+
50+
Scan the DOCX and return a list of modified text with Jinja2 variable names inserted.
51+
52+
**Arguments**:
53+
54+
- `docx_path` - path to the DOCX file
55+
- `custom_people_names` - a tuple of custom names and descriptions to use in addition to the default ones. Like: (&quot;clients&quot;, &quot;the person benefiting from the form&quot;)
56+
57+
58+
**Returns**:
59+
60+
A list of tuples, each containing a paragraph number, run number, and the modified text of the run.
61+
62+
<a id="ALDashboard.docx_wrangling.modify_docx_with_openai_guesses"></a>
63+
64+
#### modify\_docx\_with\_openai\_guesses(docx\_path: str)
65+
66+
```python
67+
def modify_docx_with_openai_guesses(docx_path: str) -> docx.document.Document
68+
```
69+
70+
Uses OpenAI to guess the variable names for a document and then modifies the document with the guesses.
71+
72+
**Arguments**:
73+
74+
- `docx_path` _str_ - Path to the DOCX file to modify.
75+
76+
77+
**Returns**:
78+
79+
- `docx.Document` - The modified document, ready to be saved to the same or a new path
80+

0 commit comments

Comments
 (0)