From e0d448f56b0834f38b7317e3b1db72a361c78fbf Mon Sep 17 00:00:00 2001 From: Quinten Steenhuis Date: Wed, 1 Jul 2026 15:44:45 -0400 Subject: [PATCH] Standardize capitalization of docassemble --- .gitignore | 3 +- .../rebuild-lightsail-instance.md | 16 ++-- .../run-docassemble-docker-vscode.md | 12 +-- .../running-docassemble-without-aws.md | 24 +++--- docs/admin_guide_docassemble/setup-server.md | 16 ++-- .../updates-and-maintenance.md | 70 +++++++-------- docs/archive/bootcamp.md | 12 +-- docs/archive/working_with_teams.md | 2 +- docs/authoring/ai_checklist_field_labeling.md | 2 +- docs/authoring/ai_mcp_and_rest.md | 6 +- docs/authoring/authoring_with_ai.md | 10 +-- docs/authoring/customizing_interview.md | 30 +++---- docs/authoring/doc_vars_reference.md | 40 ++++----- docs/authoring/docx_templates.md | 32 +++---- .../dynamic_phrasing_based_on_values.md | 14 +-- docs/authoring/github.md | 42 ++++----- docs/authoring/name_formats.md | 4 +- docs/authoring/pdf_templates.md | 6 +- docs/authoring/weaver_overview.md | 6 +- docs/authoring/writing_review_screen.md | 2 +- docs/coding_style/accessibility.md | 4 +- docs/coding_style/coding_style_overview.md | 2 +- docs/coding_style/defense.md | 14 +-- docs/coding_style/python.md | 6 +- docs/coding_style/yaml.md | 8 +- docs/coding_style/yaml_dynamic.md | 2 +- docs/coding_style/yaml_interface.md | 6 +- docs/coding_style/yaml_structure.md | 2 +- docs/coding_style/yaml_translation.md | 8 +- .../ALDashboard/aldashboard_overview.md | 4 +- docs/components/ALDashboard/create_package.md | 2 +- .../ALDashboard/project_maintenance.md | 8 +- docs/components/ALKiln/automated_testing.mdx | 4 +- docs/components/ALKiln/security.mdx | 2 +- docs/components/ALKiln/setup.mdx | 4 +- docs/components/ALKiln/troubleshooting.mdx | 6 +- docs/components/ALKiln/writing_tests.mdx | 6 +- .../althemetemplate_overview.md | 28 +++--- docs/components/ALToolbox/Addup.md | 2 +- .../ALToolbox/altoolbox_overview.md | 8 +- docs/components/ALToolbox/llms.md | 4 +- docs/components/ALToolbox/misc.md | 8 +- docs/components/ALToolbox/save_input_data.md | 2 +- docs/components/AssemblyLine/al_courts.md | 2 +- docs/components/AssemblyLine/al_document.md | 4 +- .../AssemblyLine/al_document_overview.md | 22 ++--- docs/components/AssemblyLine/al_general.md | 4 +- .../AssemblyLine/al_general_overview.md | 16 ++-- .../AssemblyLine/al_reminders_overview.md | 10 +-- .../AssemblyLine/answer_set_intakes.md | 2 +- docs/components/AssemblyLine/answer_sets.md | 6 +- .../AssemblyLine/custom_jinja_filters.md | 6 +- docs/components/AssemblyLine/error_actions.md | 2 +- .../AssemblyLine/magic_variables.md | 12 +-- docs/components/AssemblyLine/navigation.md | 4 +- .../AssemblyLine/project_maintenance.md | 8 +- .../AssemblyLine/reserved_keywords.md | 4 +- docs/components/AssemblyLine/sessions.md | 6 +- docs/components/AssemblyLine/signatures.md | 2 +- docs/components/AssemblyLine/translation.md | 16 ++-- .../components/EFSPIntegration/conversions.md | 2 +- .../efiling_through_docassemble.md | 6 +- docs/components/EFSPIntegration/efm_client.md | 2 +- .../EFSPIntegration/efsp_overview.md | 16 ++-- .../InterviewStats/interviewstats_overview.md | 14 +-- docs/contributors.md | 2 +- .../basic-troubleshooting.md | 28 +++--- .../controlling-interview-order.md | 42 ++++----- docs/docassemble_intro/hello-world.md | 32 +++---- .../introduction-to-docassemble.md | 32 +++---- docs/docassemble_intro/jinja2.md | 6 +- docs/docassemble_intro/logic.md | 10 +-- docs/docassemble_intro/mako.md | 2 +- docs/docassemble_intro/markdown.md | 6 +- .../object-oriented-programming.md | 60 ++++++------- .../practical-guide-docassemble.md | 26 +++--- docs/docassemble_intro/python.md | 18 ++-- .../docassemble_intro/repeated-information.md | 86 +++++++++---------- docs/docassemble_intro/theming-docassemble.md | 26 +++--- docs/docassemble_intro/working-with-docx.md | 8 +- docs/docassemble_intro/yaml.md | 36 ++++---- docs/get_started/al_project_architecture.md | 10 +-- docs/get_started/beginners_guide.md | 12 +-- docs/get_started/development_roadmap.md | 6 +- docs/get_started/installation.md | 14 +-- docs/get_started/intro.md | 38 ++++---- docs/get_started/plan_interview.md | 2 +- docs/get_started/resources.mdx | 16 ++-- docs/overview.md | 6 +- .../style_guide/question_library/addresses.md | 12 +-- docs/style_guide/question_library/gender.md | 4 +- docs/style_guide/question_library/language.md | 4 +- docs/style_guide/question_library/names.md | 6 +- docs/style_guide/question_library/pronouns.md | 4 +- docs/style_guide/question_style_navigation.md | 6 +- .../question_style_organize_fields.md | 2 +- docs/style_guide/style_guide_formatting.md | 4 +- docs/style_guide/style_guide_readability.md | 2 +- docs/volunteer/flows.mdx | 6 +- docs/volunteer/volunteer.mdx | 6 +- docusaurus.config.js | 2 +- make_interview_docs.py | 2 +- sidebars.js | 6 +- src/pages/index.tsx | 10 +-- 104 files changed, 628 insertions(+), 627 deletions(-) diff --git a/.gitignore b/.gitignore index 734f4a60e..d6e5c4fbb 100644 --- a/.gitignore +++ b/.gitignore @@ -28,4 +28,5 @@ yarn.lock .yarn .yarn/ .pnp.cjs -.pnp.loader.mjs \ No newline at end of file +.pnp.loader.mjs +.codex diff --git a/docs/admin_guide_docassemble/rebuild-lightsail-instance.md b/docs/admin_guide_docassemble/rebuild-lightsail-instance.md index 6a7bb52da..8e10e4a85 100644 --- a/docs/admin_guide_docassemble/rebuild-lightsail-instance.md +++ b/docs/admin_guide_docassemble/rebuild-lightsail-instance.md @@ -4,7 +4,7 @@ title: Rebuilding your AWS Lightsail instance sidebar_label: Rebuilding your AWS Lightsail instance --- -## Rebuilding your Docassemble server +## Rebuilding your docassemble server Periodically, a new version of Ubuntu that runs in your Lightsail container will be available. A new [Long-term Support (LTS)](https://wiki.ubuntu.com/LTS) @@ -17,23 +17,23 @@ the specifications. For example, you can upgrade to a container with more RAM, CPUs, or storage space. The good news is that you can update the Ubuntu software in your Lightsail -container and connect it to your existing Docassemble database. This saves time and +container and connect it to your existing docassemble database. This saves time and minimizes changes. ## Before you begin This process involves backing up files, creating a new AWS Lightsail instance, and connecting the new instance to your database. It will create a new Docker container. -The new Docker container will be running the latest version of Docassemble and other +The new Docker container will be running the latest version of docassemble and other installed packages. The process usually takes around 1 hour, so do it when you can -afford your Docassemble server to be unavailable for a while. +afford your docassemble server to be unavailable for a while. -This guide assumes you already have an existing, functional Docassemble server with +This guide assumes you already have an existing, functional docassemble server with the following setup: - AWS Lightsail instance - AWS S3 data storage - Docker container - - Docassemble web app + - docassemble web app It also assumes you can access all those items through AWS, including SSH access to the Lightsail instance. See @@ -83,7 +83,7 @@ When complete, in AWS, go to the Lightsail instance and click **Stop**. ## Back up S3 files -You can now make a copy of the Docassemble files that are stored in your S3 bucket. Most +You can now make a copy of the docassemble files that are stored in your S3 bucket. Most of the time you won't need to use these backups. It's reassuring to have a backup copy. Sign into AWS, and go to your Amazon S3 Buckets. Click on the server you want to upgrade. @@ -102,7 +102,7 @@ In AWS Lightsail, you can make a new instance by following these steps. - Be sure to match the geographical zone where old server is located. - Select the platform: Unix/Linux. - Select a blueprint: Under the 'Operating System (OS) only' tab, select Ubuntu 22.04 LTS (or the latest version). - - Choose your instance plan: Most new Docassemble instances use the 4GB Memory option. + - Choose your instance plan: Most new docassemble instances use the 4GB Memory option. - Give your server a name under Identify your instance. This can't be the same as your existing instance. You might want to include the Ubuntu version or year. It is helpful to include something like "Dev" or "Prod" to keep these types of severs distinct. For example, you could name the diff --git a/docs/admin_guide_docassemble/run-docassemble-docker-vscode.md b/docs/admin_guide_docassemble/run-docassemble-docker-vscode.md index ac2eb9c9c..8810c84c1 100644 --- a/docs/admin_guide_docassemble/run-docassemble-docker-vscode.md +++ b/docs/admin_guide_docassemble/run-docassemble-docker-vscode.md @@ -1,7 +1,7 @@ --- slug: run-docassemble-docker-vscode -title: Setup & Run Docassemble with Docker and VS Code -sidebar_label: Docassemble with Docker and VS Code +title: Setup & Run docassemble with Docker and VS Code +sidebar_label: docassemble with Docker and VS Code --- Author: [Dele Omotosho](https://github.com/deletosh) @@ -108,7 +108,7 @@ Skip this step on MacOS ![](https://i.imgur.com/LRiO87R.gif) ## Install Python and docassemble command-line app -Docassemble is written in the Python programming language. To make docassemble work offline, we need to install Python. +docassemble is written in the Python programming language. To make docassemble work offline, we need to install Python. ### Install Python on WSL Skip this step on MacOS @@ -161,7 +161,7 @@ Here’s how: ![](https://i.imgur.com/GF8SmxY.gif) - Open your browser and go to `http://localhost`. You might see this ![](https://i.imgur.com/VaFLb62.png) -- After a few minutes, you should see Docassemble running. +- After a few minutes, you should see docassemble running. - Sign in with the default password: - username: admin@admin.com - password: password @@ -172,7 +172,7 @@ Here’s how: ### Run your first offline docassemble Our main setup is now complete. Let's test our first interview. -First, go to Docassemble running on your system. In your browser, type **http://localhost**, in the navigation section, click **My Profile**. +First, go to docassemble running on your system. In your browser, type **http://localhost**, in the navigation section, click **My Profile**. ![](https://i.imgur.com/Wq4KE1X.png) @@ -221,7 +221,7 @@ When we make changes to our files on VS Code, we need to re-run the `dainstall - ## Points to have on mind while writing interviews locally -here are some things you need to keep in mind with developing Docassemble +here are some things you need to keep in mind with developing docassemble locally: - Every docassemble project is self-contained and you need to re-start Docker in each project. diff --git a/docs/admin_guide_docassemble/running-docassemble-without-aws.md b/docs/admin_guide_docassemble/running-docassemble-without-aws.md index aa77e6ce0..5d6f6ae53 100644 --- a/docs/admin_guide_docassemble/running-docassemble-without-aws.md +++ b/docs/admin_guide_docassemble/running-docassemble-without-aws.md @@ -1,12 +1,12 @@ --- slug: running-without-aws -title: Running Docassemble without AWS and S3 -sidebar_label: Running Docassemble without AWS +title: Running docassemble without AWS and S3 +sidebar_label: Running docassemble without AWS --- ## Motivation -In most situations, we recommend that you follow ["Installing a Docassemble Server"](setup-server) and use a hosted +In most situations, we recommend that you follow ["Installing a docassemble Server"](setup-server) and use a hosted virtual server with S3 compatible storage, which will give you more resilient servers and easier backups. If for some reason you need to host all of you servers on premises and cannot use cloud servers, this guide should be helpful. @@ -16,16 +16,16 @@ be helpful. These are mostly the same steps from ["Choose a DNS Name"](setup-server#choose-a-dns-name) and ["Create an 'A' record"](setup-server#create-an-a-record-that-points-to-the-reserved-ip-address-in-your-dns-providers-website). If you are hosting your own servers, you will need to find out what IP address you have and point the 'A' record to that address. -## Start the Docassemble server +## Start the docassemble server ### Install Docker -Even if you are running Docassemble on your own server, we still recommend that you use Docker -to run docassemble. As described in [the Docassemble documentation](https://docassemble.org/docs/installation.html#docker), running Docassemble without Docker is a significantly complicated exercise, with multiple long-running and reoccuring processes, and there are not many benefits that you can get from doing it. +Even if you are running docassemble on your own server, we still recommend that you use Docker +to run docassemble. As described in [the docassemble documentation](https://docassemble.org/docs/installation.html#docker), running docassemble without Docker is a significantly complicated exercise, with multiple long-running and reoccuring processes, and there are not many benefits that you can get from doing it. -So, the first step to starting the Docassemble server is to install Docker. This can follow the same steps from ["Install Docker"](setup-server#install-docker). If you are running on a different OS than linux, you should follow [Docker's official installation instructions](https://www.docker.com/get-started/). +So, the first step to starting the docassemble server is to install Docker. This can follow the same steps from ["Install Docker"](setup-server#install-docker). If you are running on a different OS than linux, you should follow [Docker's official installation instructions](https://www.docker.com/get-started/). -### Start Docassemble +### Start docassemble You can first create an `env.list` file, which should contain the following: @@ -39,15 +39,15 @@ DAEXTRAFONTS=false DAGOOGLEFONTS=false ``` -Then, you can start Docassemble. +Then, you can start docassemble. ```bash docker run -d -p 443:443 -p 80:80 -v dabackup:/usr/share/docassemble/backup --restart unless-stopped --env-file env.list --stop-timeout 600 --name docassemble jhpyle/docassemble ``` -## Upgrading the Docassemble server +## Upgrading the docassemble server -The above command (specifically the `-v` argument) created a docker volume that saves all information from the `/usr/share/docassemble/backup` directory somewhere separate from the Docassemble container on your machine. To upgrade to a newer version of the Docassemble container, you can do so without any extra commands handling the data. +The above command (specifically the `-v` argument) created a docker volume that saves all information from the `/usr/share/docassemble/backup` directory somewhere separate from the docassemble container on your machine. To upgrade to a newer version of the docassemble container, you can do so without any extra commands handling the data. ```bash docker stop -t 600 docassemble @@ -73,7 +73,7 @@ at any time. ## Restoring Backup data If you want to rollback to data from a certain date, first stop the existing -Docassemble container, and create (but don't start) a new one: +docassemble container, and create (but don't start) a new one: ```bash docker stop -t 600 docassemble diff --git a/docs/admin_guide_docassemble/setup-server.md b/docs/admin_guide_docassemble/setup-server.md index 31b41e7ce..89f69edd9 100644 --- a/docs/admin_guide_docassemble/setup-server.md +++ b/docs/admin_guide_docassemble/setup-server.md @@ -7,7 +7,7 @@ sidebar_label: Installing a docassemble server # What this guide is There are a lot of [ways you can install -Docassemble](https://docassemble.org/docs/installation.html). This is one quick +docassemble](https://docassemble.org/docs/installation.html). This is one quick path that will help you get started quickly without having to make your own choices. @@ -213,7 +213,7 @@ newgrp docker ### Setup a Linux swap file -While the 4 GB RAM allocation is almost always enough, Docassemble can have odd +While the 4 GB RAM allocation is almost always enough, docassemble can have odd moments where the RAM usage spikes up quickly, which can crash the server. This is somewhat more likely to be a problem on a development server. @@ -263,7 +263,7 @@ Update the values as follows: and to set the time that daily scheduled cron scripts run. * Set LETSENCRYPTEMAIL to an email of your choice. You will receive messages at this address if your certificate is about to expire, but otherwise will not. -* In Docassemble version 1.8.14 and later, if DAEXTRAFONTS and DAGOOGLEFONTS are true they +* In docassemble version 1.8.14 and later, if DAEXTRAFONTS and DAGOOGLEFONTS are true they will install those fonts on startup. These might be necessary for your interviews that do DOCX to PDF conversion. @@ -377,14 +377,14 @@ Compose file to ensure you are setting the same flags in the new container. ## Sit back and wait -In a few minutes, your Docassemble server will be up and running. Visit the website at the DNS +In a few minutes, your docassemble server will be up and running. Visit the website at the DNS name you chose, `https://apps.example.com`. Log in with the default username and password, admin@admin.com/password. Change it to something more secure. ### Monitor progress While the server starts up, you can run this command to monitor the container's progress, if -Docassemble is the only docker container in your server: +docassemble is the only docker container in your server: ```bash docker exec -ti $(docker ps --format '{{.Names}}') sh -c "tail -f /var/log/supervisor/initialize-stderr*" @@ -392,7 +392,7 @@ docker exec -ti $(docker ps --format '{{.Names}}') sh -c "tail -f /var/log/super If you have more than one container, you can modify the command as follows: -Note the name of the Docassemble container, which should be listed in the output of `docker ps` +Note the name of the docassemble container, which should be listed in the output of `docker ps` In the command below, replace [YOUR CONTAINER NAME] with the name of your container. ```bash @@ -410,10 +410,10 @@ updating, you should just stay patient. I recommend at least 2 servers: a production server and a development server. You may also want a test server, for a total of 3. -Production should have the most stable version of Docassemble. Development can test bleeding edge code. +Production should have the most stable version of docassemble. Development can test bleeding edge code. Test should mirror Production as much as possible. -If you want to configure load balancing, that is something I have not experimented with in Docassemble. Cost +If you want to configure load balancing, that is something I have not experimented with in docassemble. Cost will be much higher but it may be worthwhile. You still will want at least a test/dev and production environment. ## Further reading diff --git a/docs/admin_guide_docassemble/updates-and-maintenance.md b/docs/admin_guide_docassemble/updates-and-maintenance.md index efe8737ff..6aa9d410e 100644 --- a/docs/admin_guide_docassemble/updates-and-maintenance.md +++ b/docs/admin_guide_docassemble/updates-and-maintenance.md @@ -4,12 +4,12 @@ title: Securing and maintaining your server sidebar_label: Securing and maintaining your server --- -## Securing Docassemble +## Securing docassemble -Docassemble has not had any major security incidents in its history. But the +docassemble has not had any major security incidents in its history. But the higher profile your deployment, the more likely you are to have an individual attack. Such attacks are hard to entirely prevent. The best way to keep -Docassemble secure is by upgrading on a regular basis. +docassemble secure is by upgrading on a regular basis. In addition: @@ -30,7 +30,7 @@ In addition: length`](https://docassemble.org/docs/config.html#maximum%20content%20length) configuration option. -You can review [Docassemble's security policy and +You can review [docassemble's security policy and documentation](https://docassemble.org/docs/security.html). Instructions on applying regular updates are below. @@ -45,7 +45,7 @@ SSHing into the container and doing a manual docker start generally resolves these problems. The alternative, manual installation of OS updates, is usually worse for most -people who run a single small Docassemble server. Just set up automated alerts +people who run a single small docassemble server. Just set up automated alerts that tell you when the website is not available. [UpTimeRobot](https://uptimerobot.com/) is one free option that works well for @@ -55,9 +55,9 @@ If you do not have automatic updates enabled, you can install the [unattended-upgrades](https://wiki.debian.org/UnattendedUpgrades) package manually using your host operating system's package manager. -## Upgrading to a new version of Docassemble +## Upgrading to a new version of docassemble -Docassemble has two parts: +docassemble has two parts: 1. a [Python](../docassemble_intro/python.md) web application, built around the [Flask framework](https://flask.palletsprojects.com/en/2.2.x/) @@ -74,13 +74,13 @@ framework](https://flask.palletsprojects.com/en/2.2.x/) - [Nginx](https://www.nginx.com/) as a web server -Docassemble is updated regularly. As of this writing, releases come out almost +docassemble is updated regularly. As of this writing, releases come out almost every few weeks. Most updates affect only the frontend, not the Ubuntu operating system or its installed applications. ### When to update -It's a good idea to stay up to date with the latest version of Docassemble. But +It's a good idea to stay up to date with the latest version of docassemble. But sometimes the very latest release can have bugs. It's best to test out the release on a development or staging server before you install it on your production server. @@ -89,28 +89,28 @@ If you get too far behind from the latest version, there's always a chance that you will run into a bug that only occurs because your version was too far out of date. A good cadence is upgrading about once a month. -Jonathan Pyle, the Docassemble author, is generally very responsive to bug +Jonathan Pyle, the docassemble author, is generally very responsive to bug fixes, as well as helping authors install a fixed version. The best way to get -help with an upgrade gone wrong is to use the Docassemble +help with an upgrade gone wrong is to use the docassemble [Slack](https://docassemble.org/docs/support.html#tocAnchor-1-1) channel. -Upgrade the Docassemble frontend every few weeks. Upgrade the container every +Upgrade the docassemble frontend every few weeks. Upgrade the container every six months or so, unless you need a feature right away. But wait a week or two after the new container is released to make sure there are no lingering bugs. -### Updates to the Docassemble frontend +### Updates to the docassemble frontend You can update the Python packages and Flask frontend by using the ["Upgrade"](https://docassemble.org/docs/admin.html#upgrade) button in the package management menu. This is safe to do on a monthly basis, but keep in mind that you should test -the upgraded version of Docassemble on a development or staging server before +the upgraded version of docassemble on a development or staging server before installing on your production server. -### Updates to the Docassemble container +### Updates to the docassemble container -Updates to the base Docassemble OS image (and Python, LibreOffice, etc) are +Updates to the base docassemble OS image (and Python, LibreOffice, etc) are generally optional. They come with new features that aren't possible to provide by updating just the frontend. But if you do not want or need those new features, you can wait to upgrade. @@ -121,11 +121,11 @@ want to wait for a few minor releases (which might fix critical bugs) before you upgrade your container. The newest container upgrade is the most likely to have a few bugs to work out. -The Docassemble [Changelog](https://docassemble.org/docs/changelog.html) +The docassemble [Changelog](https://docassemble.org/docs/changelog.html) announces when there is a new feature that requires a container upgrade. Just searching on the page for the word "container" should tell you. -Whenever you upgrade the Docassemble container, you have a small chance of +Whenever you upgrade the docassemble container, you have a small chance of losing data, because the upgrade process involves starting an entirely new Docker container and copying the information into it, either from a shared Docker volume or from S3. If the Docker container did not properly shut down, @@ -161,7 +161,7 @@ To prepare for the upgrade: Here is the upgrade process: -1. SSH into the virtual machine or server that hosts your Docassemble docker container +1. SSH into the virtual machine or server that hosts your docassemble docker container 2. In the virtual machine's command line, copy and run the following commands: @@ -185,7 +185,7 @@ docker system prune ## Updating individual packages -You can upgrade individual Python packages and Docassemble interviews on your +You can upgrade individual Python packages and docassemble interviews on your server by [visiting the Package Management page](https://docassemble.org/docs/packages.html#updating). and clicking the "update" button next to the package you want to update. @@ -195,7 +195,7 @@ will upgrade all of the key packages that you need, except for the ones that represent individual interviews you authored. The exception is if you installed a package or series of packages that is -maintained by someone other than the Docassemble author, such as the +maintained by someone other than the docassemble author, such as the Assembly Line packages. ### Updating the AssemblyLine packages @@ -230,8 +230,8 @@ the ones that are intended for wider use and installation on production servers. Therefore, we recommend that most authors install AssemblyLine from PyPi instead of directly using the GitHub URL. -## Docassemble server maintenance checklist -On August 24, 2023, ILAO gave a presentation on Maintaining your Docassemble +## docassemble server maintenance checklist +On August 24, 2023, ILAO gave a presentation on Maintaining your docassemble server as part of a [Technology Initiative Grant funded by the Legal Services Corporation](https://www.lsc.gov/grants/technology-initiative-grant-program/tig-program-description). @@ -246,7 +246,7 @@ What follows is a condensed format to serve as a checklist. ### AWS Lightsail instance -This server instance runs Linux, typically Ubuntu. It is sometimes called the host. Docassemble +This server instance runs Linux, typically Ubuntu. It is sometimes called the host. docassemble software runs on it. - How to monitor - Log into AWS console and see if it is running. Set up CPU utilization alerts @@ -289,7 +289,7 @@ sudo shutdown -r now ### AWS S3 bucket -This is where the Docassemble database lives. Separating the Docassemble data from the software makes it +This is where the docassemble database lives. Separating the docassemble data from the software makes it easier to maintain and rebuild if needed. - How to monitor - Log into the AWS console. Go to S3. You should see files within each bucket. - What to back up - The most important files to back up are: @@ -297,42 +297,42 @@ easier to maintain and rebuild if needed. - redis.rdb - docassemble (inside postgres folder) - When to back up - Every few months or as often as you want to have a backup you could rebuild from. By - default, Docassemble makes a daily backup of these and other files. Each daily backup is stored in the /backups + default, docassemble makes a daily backup of these and other files. Each daily backup is stored in the /backups folder. It is important to make backups of the docassemble database and redis.rdb files at about the same time. If these -files are out of sync files when restoring, user accounts and data sync errors may result. See the Docassemble +files are out of sync files when restoring, user accounts and data sync errors may result. See the docassemble documentation to learn more about [Recovery from backup files](https://docassemble.org/docs/docker.html#recovery). ### Docker container -This virtual machine is installed on the Lightsail instance and runs its own version of Linux. The Docassemble +This virtual machine is installed on the Lightsail instance and runs its own version of Linux. The docassemble software runs within. Using a virtual machine adds to resiliency, though it also requires its own maintenance. - How to monitor - Use `docker ps` command to make sure it is running. - How to update - See - [Updates to the Docassemble container](maintaining-docassemble#updates-to-the-docassemble-container). + [Updates to the docassemble container](maintaining-docassemble#updates-to-the-docassemble-container). You will use these commands: `docker stop, pull, run,` and `prune`. - If you [updated the nginx timeout to 5 minutes](https://assemblyline.suffolklitlab.org/docs/installation/#increase-nginx-timeouts-to-5-minutes) earlier, you will need to redo it. - This will pull the latest version of each package unless specific version of a package was pinned via PyPI. - - When to update - If the [Docassemble Change Log](https://docassemble.org/docs/changelog.html) has an update - that says "**System upgrade required**," rebuild the Docker container after updating the Docassemble web + - When to update - If the [docassemble Change Log](https://docassemble.org/docs/changelog.html) has an update + that says "**System upgrade required**," rebuild the Docker container after updating the docassemble web app. Otherwise, about every 6 months. -### Docassemble web app +### docassemble web app -This is the Docassemble software users and developers most often interact with through interviews and the +This is the docassemble software users and developers most often interact with through interviews and the Playground. - How to monitor - If you can get to the Playground, My Interviews, or an individual program, then it's working. [UptimeRobot](https://uptimerobot.com/) can be used to receive server up/down notifications by email. - How to update - Log in as an administrator. Go to Package Management. Click the "Upgrade" button. See - [Updates to the Docassemble frontend](maintaining-docassemble#updates-to-the-docassemble-frontend) + [Updates to the docassemble frontend](maintaining-docassemble#updates-to-the-docassemble-frontend) - When to update - Every few weeks or as needed if there is a critical bug fix or a desired new feature. ### Packages -These are the program code, frameworks, and utilities that run on the Docassemble platform. The Assembly Line package +These are the program code, frameworks, and utilities that run on the docassemble platform. The Assembly Line package is an example used by many programs. - How to monitor - Monitors like [httpstatus.io](https://httpstatus.io/) or homegrown programs can check if individual programs are running. Note: These tools just check whether individual interview pages are reachable. Learn about using diff --git a/docs/archive/bootcamp.md b/docs/archive/bootcamp.md index 6dda6de5e..79b58732c 100644 --- a/docs/archive/bootcamp.md +++ b/docs/archive/bootcamp.md @@ -29,8 +29,8 @@ If you are finding this page after February 18th, 2021, be sure to watch the vid Read: 1. If you are unfamiliar with the Assembly Line project, please give the [intro page](../get_started) a look -1. Read over this short [introduction to Docassemble](../docassemble_intro/introduction-to-docassemble) -1. And if you want more context, consider reading [what should you use Docassemble for?](../docassemble_intro/practical-guide-docassemble) +1. Read over this short [introduction to docassemble](../docassemble_intro/introduction-to-docassemble) +1. And if you want more context, consider reading [what should you use docassemble for?](../docassemble_intro/practical-guide-docassemble) Do: @@ -78,13 +78,13 @@ additional questions. -* [Using Github in Docassemble](../authoring/github.md) +* [Using Github in docassemble](../authoring/github.md) * Customizing basic branding with the [ALThemeTemplate](https://github.com/SuffolkLITLab/docassemble-ALThemeTemplate) package. * Logo * Intro screen * Pushing changes to Github -### Week 4: Advanced Docassemble, Installing the backend +### Week 4: Advanced docassemble, Installing the backend @@ -92,8 +92,8 @@ additional questions. * [docassemble-ALThemeTemplate](https://github.com/SuffolkLITLab/docassemble-ALThemeTemplate) package * Introduction to the docassemble.Income class * Working with tables and repeated data -* How to install the Assembly Line packages on your Docassemble server -* How to install individual packages on your Docassemble server +* How to install the Assembly Line packages on your docassemble server +* How to install individual packages on your docassemble server * Creating short links * The index page diff --git a/docs/archive/working_with_teams.md b/docs/archive/working_with_teams.md index 11b6e32e0..bd651215e 100644 --- a/docs/archive/working_with_teams.md +++ b/docs/archive/working_with_teams.md @@ -431,7 +431,7 @@ Sometimes it may be more helpful to ask the stakeholder to directly edit the tem (to make proposed formatting changes that don't directly involve variables) than to try to interpret their requests. -1. Download the templates from the Docassemble package or playground +1. Download the templates from the docassemble package or playground 1. Send the templates to the user in an email, with instructions to ignore anything inside curly brackets 1. When you get the documents back, use Word's "compare documents" feature to make sure they didn't accidentally change something they weren't supposed to change diff --git a/docs/authoring/ai_checklist_field_labeling.md b/docs/authoring/ai_checklist_field_labeling.md index 64a36c52e..55e75df44 100644 --- a/docs/authoring/ai_checklist_field_labeling.md +++ b/docs/authoring/ai_checklist_field_labeling.md @@ -20,4 +20,4 @@ Related guides (canonical details): - [Field labels to use in template files](doc_vars_reference.md) - [PDF templates](pdf_templates.md) - [DOCX templates](docx_templates.md) -- [Docassemble variable naming in Python](../coding_style/python.md) +- [docassemble variable naming in Python](../coding_style/python.md) diff --git a/docs/authoring/ai_mcp_and_rest.md b/docs/authoring/ai_mcp_and_rest.md index 6e79276cc..a1e3e24a7 100644 --- a/docs/authoring/ai_mcp_and_rest.md +++ b/docs/authoring/ai_mcp_and_rest.md @@ -7,7 +7,7 @@ slug: ai_mcp_and_rest You can use AI-assisted authoring tools without installing `docassemble.ALWeaver` or `docassemble.ALDashboard` in your local Python environment. -Instead, call the APIs on a running Docassemble server: +Instead, call the APIs on a running docassemble server: - ALWeaver REST API (`/al/api/v1/weaver...`) - ALDashboard REST API (`/al/api/v1/dashboard/...`) @@ -17,12 +17,12 @@ Instead, call the APIs on a running Docassemble server: - Keeps your AI workflow lightweight on local machines. - Lets your AI agent work against one shared, server-side environment. -- Avoids local dependency setup for OCR, PDF tooling, and Docassemble internals. +- Avoids local dependency setup for OCR, PDF tooling, and docassemble internals. - Makes async jobs available for longer-running tasks. ## Authentication -These endpoints use Docassemble API auth (`api_verify()`), typically: +These endpoints use docassemble API auth (`api_verify()`), typically: - `X-API-Key: YOUR_API_KEY`, or - `Authorization: Bearer ...` (if configured on your server). diff --git a/docs/authoring/authoring_with_ai.md b/docs/authoring/authoring_with_ai.md index d52cd26a5..bc4931e39 100644 --- a/docs/authoring/authoring_with_ai.md +++ b/docs/authoring/authoring_with_ai.md @@ -5,7 +5,7 @@ sidebar_label: Coding with AI assistance slug: authoring_with_ai --- -Here's an experimental workflow for using AI assistance to generate Docassemble interviews, +Here's an experimental workflow for using AI assistance to generate docassemble interviews, while leveraging the Assembly Line framework's predictable, rules-based assistance at every stage where it can be helpful. @@ -22,13 +22,13 @@ a local code editor is best in order to run the different pieces. You might use: * GitHub Copilot with VS Code, free for students, faculty, and staff at universities and only $10/month. * OpenAI Codex, which is included with a ChatGPT+ subscription ($20/month). -* Google Gemini or Google's Antigravity, which has a modest free tier (might not be enough to develop a full Docassemble app). +* Google Gemini or Google's Antigravity, which has a modest free tier (might not be enough to develop a full docassemble app). * Claude Code, which also has a $20/month tier. In fact, you might be able to point your AI agent at this page and have it follow these instructions. You just need: -a. Install all of the build dependencies for Docassemble as well as packages that might +a. Install all of the build dependencies for docassemble as well as packages that might be needed to run FormFyxer ```bash @@ -149,7 +149,7 @@ Reference (ALWeaver entry point): - [ ] Rename PDF fields to AssemblyLine conventions using clear nouns (`users`, `children`, `caregivers`) and contextual dates (avoid `day`, `month`, `year`). - [ ] Ensure unique names for multiple parties and signatures (e.g., `users1`, `users2`). - [ ] If a PDF radio group is implemented as checkboxes, split into separate checkbox fields and map with boolean expressions in YAML. -- [ ] For checkboxes, map True/False and let Docassemble handle export values. +- [ ] For checkboxes, map True/False and let docassemble handle export values. - [ ] After PDF edits, re-verify that the YAML field mapping matches the PDF field names. Docs: @@ -230,7 +230,7 @@ https://taxonomy.legal/ ## Translation -At the moment, translating a Docassemble interview does require a running Docassemble server to pull in the various strings +At the moment, translating a docassemble interview does require a running docassemble server to pull in the various strings from the different included packages. Install the interview in a playground and use the ALDashboard translation tool to do the translation. This is likely to be a human step for now. diff --git a/docs/authoring/customizing_interview.md b/docs/authoring/customizing_interview.md index 819776479..12ec5e8d3 100644 --- a/docs/authoring/customizing_interview.md +++ b/docs/authoring/customizing_interview.md @@ -5,7 +5,7 @@ sidebar_label: Editing your interview slug: customizing_interview --- -## Edit your completed draft interview in the Docassemble playground +## Edit your completed draft interview in the docassemble playground While the Weaver is a menu-driven, step-by-step process, you'll make further edits in the Playground. In the playground, you can directly edit the @@ -22,8 +22,8 @@ many changes can be understood by reading the text and then experimenting. This pages offers information about making some common, simple edits. You may also want to take this time to read through the materials in -[Introduction to Docassemble](../docassemble_intro/introduction-to-docassemble) -about the underlying Docassemble platform and how it works. +[Introduction to docassemble](../docassemble_intro/introduction-to-docassemble) +about the underlying docassemble platform and how it works. ## Double-check that you got things right in the Weaver stage @@ -54,11 +54,11 @@ Before downloading the package, turn off that behavior: ::: First, create a new "Project" in your playground. Using projects will -help you keep your Docassemble code organized. +help you keep your docassemble code organized. ![playground | projects ](../assets/playground_projects.png) -Next, upload this file to the Docassemble playground's `Packages` folder. +Next, upload this file to the docassemble playground's `Packages` folder. ![Folders | Packages ](../assets/playground_packages_menu.png) @@ -88,7 +88,7 @@ Then, change the text that you want to change, or change the order of fields. Below we describe some of the most common starting customizations you will make, especially changes that interact with an Assembly Line convention. -You can use any [Docassemble feature](https://docassemble.org/docs/fields.html) +You can use any [docassemble feature](https://docassemble.org/docs/fields.html) in your interview. ## Marking a field as optional (not required) @@ -146,7 +146,7 @@ quickly. For example, if we wanted to add this question to the interview order block below, you would add the variable `temporary_needed` to the interview order block because -`temporary_needed` is the first variable on this screen. When Docassemble tries to +`temporary_needed` is the first variable on this screen. When docassemble tries to define `temporary_needed`, it will show this screen and ask all of the questions mentioned on it. @@ -249,7 +249,7 @@ multiple variables in one **if** statement, you need to use the more complex When you use `js show if`, you need to use a JavaScript expression that uses the function `val()` at least once. `val()` is a JavaScript function that returns the value of a variable name that is visible on screen. It takes the name of the -Docassemble variable in quotes as its only parameter. +docassemble variable in quotes as its only parameter. Here is a small example of a `js show if` expression: @@ -274,7 +274,7 @@ documentation](https://docassemble.org/docs/fields.html#js%20show%20if) to learn how to use different combinations of values in a `js show if` expression. The key is that you'll use ordinary JavaScript keywords to do any comparisons. JavaScript is its own language, and keywords such as "or", "and" and even "==" -work slightly differently, as explained in the Docassemble documentation. You +work slightly differently, as explained in the docassemble documentation. You can also use a general resource that documents JavaScript to learn more. ## Adding conditional logic inside an attachment block @@ -457,9 +457,9 @@ is just a YAML file named `ql_baseline.yml`. It contains questions about people's names, addresses, birthdates, gender and pronouns, and party roles. -1. **You can always write your own version of a question in the library.** Docassemble reads your YAML file from top +1. **You can always write your own version of a question in the library.** docassemble reads your YAML file from top to bottom, so if you add your question that defines the same -variables after the include block, Docassemble will always use your version. +variables after the include block, docassemble will always use your version. 1. **You maybe shouldn't write your own version.** The question library questions are tested by real users. Some customization is to be expected, but be sure you have a clear reason for your choice. @@ -540,7 +540,7 @@ Just like `generic object` works for any object, the variable `i` (and other [in
More about `i` and `x` - Learn more about `i` and `x` and how they work in Docassemble code in this Document Assembly Line workshop: + Learn more about `i` and `x` and how they work in docassemble code in this Document Assembly Line workshop:
@@ -548,7 +548,7 @@ Just like `generic object` works for any object, the variable `i` (and other [in ### Learning why a question got asked -Every screen in Docassemble is asked for a reason, and you can +Every screen in docassemble is asked for a reason, and you can always find out why. 1. Click the "source" `` icon in the top navigation bar. @@ -642,7 +642,7 @@ any number, or at least one for every list of people in your interview. If you didn't answer this at the time, you'll get asked it when you run the interview each time. -Fix this by editing the [definition of the list](#list-definition) so Docassemble knows +Fix this by editing the [definition of the list](#list-definition) so docassemble knows there is at least one, more than one, or any number of people in the list. @@ -696,7 +696,7 @@ For example: objects: - attorneys: ALPeopleList # Uses the default `there_are_any` question, no minimum number - users: ALPeopleList.using(there_are_any=True) # Will prompt one at a time, but asks for at least one - - other_parties: ALPeopleList.using(ask_number=True, target_number=1) # Tells Docassemble there is exactly one other_party + - other_parties: ALPeopleList.using(ask_number=True, target_number=1) # Tells docassemble there is exactly one other_party ``` #### Placing a limit on the number of items gathered in a list diff --git a/docs/authoring/doc_vars_reference.md b/docs/authoring/doc_vars_reference.md index 96f8b765f..6ebb7a700 100644 --- a/docs/authoring/doc_vars_reference.md +++ b/docs/authoring/doc_vars_reference.md @@ -36,7 +36,7 @@ A blank space on a paper form is usually called a `form field`, or `field` for short. We call adding unique names that refer to those blank spaces `labeling` them. -When you access the labeled field in your Docassemble code, it is usually called +When you access the labeled field in your docassemble code, it is usually called a `variable`. ### General rules for labels @@ -143,7 +143,7 @@ scratch. You still have the option to customize those questions later. :::note A note about objects For those with programming experience, we turn most of the field labels that we recognize into `objects`. Learn more about the [Individual -object](https://docassemble.org/docs/objects.html#Individual) in the Docassemble +object](https://docassemble.org/docs/objects.html#Individual) in the docassemble documentation. ::: @@ -179,11 +179,11 @@ When the form is automated in the Weaver, the field name becomes part of a list: list you are accessing, with the first item starting at 0: `users[0]` represents the first user, `users[1]` the second, and so on. -The Docassemble and DOCX variable name `users[0]` is the equivalent of `users` +The docassemble and DOCX variable name `users[0]` is the equivalent of `users` or `users1` in a PDF label. `users[1]` is the equivalent of `user2`. Names are not transformed at all when you work in a DOCX template. You need to use the -Docassemble syntax from the beginning if you are identifying a specific person in a list. +docassemble syntax from the beginning if you are identifying a specific person in a list. ## Labels for people, places, and things @@ -228,7 +228,7 @@ prompt you to decide if they should be treated as like people in the automation Substitute the name `users` with any of the names listed above. - PDF variation | Docassemble / DOCX form | Meaning + PDF variation | docassemble / DOCX form | Meaning -------------------|-------------------------------------------|----------- `users1_name` or `users1_name_full` | `users[0]` or `users[0].name.full()` | Full name `users1_name_first` | `users[0].name.first` or `users[0].familiar()` | First name only @@ -247,12 +247,12 @@ In a DOCX file, writing out `users` will list all of the `users` added to the form, separated by a comma. Writing `users.familiar()` will list all of the first names of each `user` separated by a comma. -This works for any Docassemble list. +This works for any docassemble list. ### Demographic data for people {#person-demographics} Substitute any name for a person for `users` below. - PDF variation | Docassemble / DOCX form | Meaning + PDF variation | docassemble / DOCX form | Meaning ----------------------|---------------------------|----------- `users1_birthdate` | `users[0].birthdate` | Birthdate (formatted like January 1, 2021 by default) `users1_age` | `users[0].age_in_years()` | Calculated age (based on birthdate) @@ -270,7 +270,7 @@ Substitute any name for a person for `users` below. Substitute any name for a person for `users` below. - PDF variation | Docassemble / DOCX form | Meaning + PDF variation | docassemble / DOCX form | Meaning -----------------------------|----------------------------|----------- `users1_address_block` | `users[0].address.block()` | Full address, on multiple lines `users1_address_on_one_line` | `users[0].address.on_one_line()` | Full address on one line @@ -293,7 +293,7 @@ to ask a separate question about the user's mailing address. Substitute any name for a person for `users` below. - PDF variation | Docassemble / DOCX form | Meaning + PDF variation | docassemble / DOCX form | Meaning -----------------------------|----------------------------|----------- `users1_phone_number` | `users[0].phone_number` | Phone number `users1_mobile_number` | `users[0].mobile_number` | A phone number explicitly labeled as the "mobile" number @@ -304,14 +304,14 @@ Substitute any name for a person for `users` below. Substitute any name for a person for `users` below. - PDF variation | Docassemble / DOCX form | Meaning + PDF variation | docassemble / DOCX form | Meaning -----------------------------|----------------------------|----------- `users1_signature` | `users[0].signature` | Signature `signature_date` | `signature_date` | Date the form is completed (automatically filled in by default) ### Information about court and court processes {#courts} - PDF variation | Docassemble / DOCX form | Meaning + PDF variation | docassemble / DOCX form | Meaning -----------------------------|----------------------------|----------- `trial_court` | `trial_court` | Court's full name, like: "Eastern Housing Court" `trial_court_county` | `trial_court.address.county` | County where court is located @@ -322,17 +322,17 @@ Substitute any name for a person for `users` below. ## Special endings to mark data types -Usually, it is not recommended to mark the type of fields in Docassemble. There are +Usually, it is not recommended to mark the type of fields in docassemble. There are a few exceptions that both mark type and carry a separate meaning that the Weaver will recognize. ### Indicating paired yes/no checkboxes {#yes-no-fields} -The Weaver turns paired yes/no checkboxes into a single Docassemble variable. +The Weaver turns paired yes/no checkboxes into a single docassemble variable. Use any valid keyword to replace `is_minor` in the example below. - PDF variation | Docassemble / DOCX form | Meaning + PDF variation | docassemble / DOCX form | Meaning -----------------------------|----------------------------|----------- `is_minor_yes`, `is_minor_no`| `is_minor` | Indicates the user is a minor @@ -343,7 +343,7 @@ the Weaver will automatically recognize it as a date. Replace `firm_founding` with any valid keyword in the example below. - PDF variation | Docassemble / DOCX form | Meaning + PDF variation | docassemble / DOCX form | Meaning -----------------------|----------------------------|----------- `firm_founding_date` | `firm_founding_date` | Will be recognized as a date field by the Weaver. @@ -354,7 +354,7 @@ the Weaver will automatically recognize it as a currency amount. Replace `expense_rent` or `house` with any valid keyword in the example below. - PDF variation | Docassemble / DOCX form | Meaning + PDF variation | docassemble / DOCX form | Meaning -----------------------|----------------------------|----------- `expense_rent_amount` | `expense_rent_amount` | Will be recognized as a currency value by the Weaver. `house_value` | `house_value` | Will be recognized as a currency value by the Weaver. @@ -362,7 +362,7 @@ Replace `expense_rent` or `house` with any valid keyword in the example below. ## Dealing with PDF limitations - adding the same field twice -Docassemble does not work with PDF forms that use the same label for a field +docassemble does not work with PDF forms that use the same label for a field twice. To work around this issue, annotate the second or third field with two @@ -370,7 +370,7 @@ underscores and any digit, like this: `__1`. Replace `users1_name` with any other valid field name in the example below. - PDF variation | Docassemble / DOCX form | Meaning + PDF variation | docassemble / DOCX form | Meaning -----------------------|----------------------------|----------- `users1_name__1` | `users[0]` | Allows you to label two fields in the PDF to contain the user's name. `user1_name__2` | `users[0]` | Same as above @@ -380,7 +380,7 @@ DOCX files do not have any limit on using the same variable name twice. This special syntax only applies to PDF templates. :::note Use any digit -Docassemble does not do anything with the digit. Feel free to use `__1`, `__99` or any +docassemble does not do anything with the digit. Feel free to use `__1`, `__99` or any other series of digits, in any order. ::: @@ -391,7 +391,7 @@ Getting things right at the beginning can save you a lot of time and effort. However, you can always edit your template later. When you make changes to your template, you do not need to run it through the Weaver again. You can upload -your edited template directly to the Docassemble playground's templates folder. +your edited template directly to the docassemble playground's templates folder. ## See also diff --git a/docs/authoring/docx_templates.md b/docs/authoring/docx_templates.md index 815a3e98f..910911d25 100644 --- a/docs/authoring/docx_templates.md +++ b/docs/authoring/docx_templates.md @@ -32,7 +32,7 @@ We recommend using Microsoft Word as your editor when possible if the document may need additional editing by the user. If your document will be converted into a PDF for the user, it may be useful to open the -DOCX file in Libre Office. Docassemble, by default, uses Libre Office to convert the Word +DOCX file in Libre Office. docassemble, by default, uses Libre Office to convert the Word file to PDF. Sometimes formatting glitches will be visible only when the document is opened in Libre Office. DOCX files can be very simple to work with, but we've taken the time to describe some common tasks, @@ -47,7 +47,7 @@ Microsoft Word document, surrounded by two sets of curly braces, like: `{{ varia The syntax to type in fields in a DOCX template is named `jinja2`. [Learn more about Jinja2](../docassemble_intro/jinja2) -and about [DOCX templates in Docassemble](https://docassemble.org/docs/documents.html#docx%20template%20file). +and about [DOCX templates in docassemble](https://docassemble.org/docs/documents.html#docx%20template%20file). @@ -57,7 +57,7 @@ are: 1. Fill in the blank fields, which are simply surrounded with double curly brackets: `{{ field_name }}` 1. Conditional text with `{% if some_condition %}` and `{% endif %}`, or the slight variation `{%p if some_condition %} ... {%p endif %}` to make a whole paragraph conditional. -:::caution Docassemble uses the [docxtpl](https://docxtpl.readthedocs.io/en/latest/#jinja2-like-syntax) variant of Jinja2 +:::caution docassemble uses the [docxtpl](https://docxtpl.readthedocs.io/en/latest/#jinja2-like-syntax) variant of Jinja2 docxtpl has slight differences to the more common Jinja2 format used in HTML documents. If a feature isn't working as @@ -132,7 +132,7 @@ Always using a space helps avoid you forgetting these special cases. It also hel :::info Avoid using `-` to control whitespace While in standard Jinja2 you can use a `-` to control whitespace, this won't -work reliably in Docassemble. That is because Docassemble uses [docxtpl](https://docxtpl.readthedocs.io/en/latest/#jinja2-like-syntax), not the standard Jinja2. +work reliably in docassemble. That is because docassemble uses [docxtpl](https://docxtpl.readthedocs.io/en/latest/#jinja2-like-syntax), not the standard Jinja2. Avoid using this feature in your templates. ::: @@ -157,7 +157,7 @@ Also use `{%p if %}` to control conditional items in a list, like this: 1. `{%p endif %}` Keep the condition inside the list itself. Avoid using the condition in its own -paragraph, as when Docassemble merges the two lists they may behave unpredictably. +paragraph, as when docassemble merges the two lists they may behave unpredictably. Similarly, use `tc` and `tr` to control repeated or conditional rows. Keep this in-line in one table when it makes sense. Avoid using `{%p %}` and multiple tables, as this can lead to unexpected table formatting when the two @@ -224,7 +224,7 @@ For more advanced changes to the variable text, you will use a mix of Python functions, methods, and Jinja2 filters. It's not always intuitive which to use when. In some cases, you can use more than one. -Functions and methods are either built-in to Python, Docassemble, or a custom class you create. Note that some Python functions won't work in a DOCX template. +Functions and methods are either built-in to Python, docassemble, or a custom class you create. Note that some Python functions won't work in a DOCX template. If you run into a function that doesn't work as expected, look to see if there's an equivalent filter to replace it. In most cases there will be. @@ -246,12 +246,12 @@ This is a filter with a parameter: Some sources for filters you can use: -* [Docassemble-provided Jinja2 filters](https://docassemble.org/docs/documents.html#filters) +* [docassemble-provided Jinja2 filters](https://docassemble.org/docs/documents.html#filters) * [List of built-in Jinja2 filters](https://jinja.palletsprojects.com/en/2.11.x/templates/#builtin-filters) (but note this easier to read, [unofficial version of this same list](https://tedboy.github.io/jinja2/templ14.html)) :::info -One filter you'll find yourself using frequently is the `length` filter. Docassemble doesn't make `len()` available -inside of Docassemble templates, so you must use `length` as a filter instead. For example: +One filter you'll find yourself using frequently is the `length` filter. docassemble doesn't make `len()` available +inside of docassemble templates, so you must use `length` as a filter instead. For example: ```jinja {%p if users | length > 2 %} @@ -400,7 +400,7 @@ For example, suppose every item in the list `my_list` has an attribute ``` This only works for checking one attribute, and one value. You can use `selecattr`, described below, -for more complex situations. One benefit of `filter()` is that the result will be of the special Docassemble +for more complex situations. One benefit of `filter()` is that the result will be of the special docassemble DAList class. ### Create a sum with the `sum` filter @@ -465,12 +465,12 @@ To try this fix: ### Troubleshooting problems with conversion to PDF Sometimes the DOCX will look right, but things like headings, numberings, and other -styles will look off when Docassemble converts your template to PDF. +styles will look off when docassemble converts your template to PDF. The first thing to check when troubleshooting a DOCX conversion to PDF is to see -how the document looks in [Libre Office](https://www.libreoffice.org/). Docassemble +how the document looks in [Libre Office](https://www.libreoffice.org/). docassemble uses Libre Office to convert DOCX to PDF, so if you can fix issues in Libre Office -on your home computer, it should look right when Docassemble converts it to PDF on the +on your home computer, it should look right when docassemble converts it to PDF on the server. #### Installing the proper fonts @@ -478,8 +478,8 @@ server. One issue you may find is that the PDF doesn't have the right fonts. There are two potential solutions: -1. You can revise your document to use the Microsoft True Type Core Fonts for the Web, which come pre-installed on Docassemble servers. These include Arial and Times New Roman. -1. You can install the fonts on the Docassemble server. The [ALDashboard](https://github.com/SuffolkLITLab/docassemble-ALDashboard)'s "Install fonts" widget can help you install a TTF (TrueType) +1. You can revise your document to use the Microsoft True Type Core Fonts for the Web, which come pre-installed on docassemble servers. These include Arial and Times New Roman. +1. You can install the fonts on the docassemble server. The [ALDashboard](https://github.com/SuffolkLITLab/docassemble-ALDashboard)'s "Install fonts" widget can help you install a TTF (TrueType) font on your server. 1. You can [embed the fonts](https://support.microsoft.com/en-us/office/benefits-of-embedding-custom-fonts-cb3982aa-ea76-4323-b008-86670f222dbc) inside the DOCX file. This might significantly increase the file size. @@ -494,7 +494,7 @@ manually. ## Quality control checklist - [ ] The DOCX template has valid Jinja syntax. You can use the [ALDashboard](https://github.com/SuffolkLITLab/docassemble-ALDashboard)'s "Validate DOCX template" widget, - installed on your own Docassemble server, to check. + installed on your own docassemble server, to check. - [ ] All of the expected standard field names are recognized by the Weaver (marked in bold when you upload and view the quality control screen) - [ ] Custom field names are all properly spelled, without typos - [ ] Run the interview with short, long, and one and many items for repeated lists to ensure that the full range of common scenarios looks proper. diff --git a/docs/authoring/dynamic_phrasing_based_on_values.md b/docs/authoring/dynamic_phrasing_based_on_values.md index 0b034062a..6b91d075b 100644 --- a/docs/authoring/dynamic_phrasing_based_on_values.md +++ b/docs/authoring/dynamic_phrasing_based_on_values.md @@ -5,7 +5,7 @@ sidebar_label: Dynamic phrasing based on values slug: dynamic_phrasing_based_on_values --- -Docassemble has several clever features that you can use in templates +docassemble has several clever features that you can use in templates and in the body of your interview to automatically rephrase text in a context specific way depending on: @@ -61,7 +61,7 @@ fields: ## Show the person's full name, without abbreviation -By default, Docassemble abbreviates an individual's middle name, so +By default, docassemble abbreviates an individual's middle name, so John Quincy Adams is printed as John Q Adams. You can write someone's full name, in a template or the interview, with the `name_full()` or `name.full(middle="full")` @@ -71,7 +71,7 @@ For example, in a DOCX template: ```jinja {{ users[0].name_full() }} {# if it is an ALIndividual #} -{{ users[0].name.full(middle="full") }} {# if it is regular Docassemble Individual #} +{{ users[0].name.full(middle="full") }} {# if it is regular docassemble Individual #} ``` And for a list of people, you can use: @@ -110,7 +110,7 @@ John or Jane If your list is a DAList or a ALPeopleList, referring to the list in the YAML or in your template results in the items all being printed, separated by a comma and with the ending word "and", thanks to -Docassemble automatically applying the function [`comma_and_list`](https://docassemble.org/docs/functions.html#comma_and_list) +docassemble automatically applying the function [`comma_and_list`](https://docassemble.org/docs/functions.html#comma_and_list) to the list. For example, if `children` is a list with "John", "Jane" and "Mary": @@ -264,7 +264,7 @@ the individual's `pronouns` attribute. `pronouns` can either be a single string, of the form "he/him/his" or "xe/xir/xirs", or a DADict with various pronouns marked as True or False, as would be created by -a Docassemble [datatype: checkboxes](https://docassemble.org/docs/fields.html#fields%20checkboxes) question. +a docassemble [datatype: checkboxes](https://docassemble.org/docs/fields.html#fields%20checkboxes) question. ### `pronoun` and `pronoun_objective` @@ -342,7 +342,7 @@ They are her shoes. ### Automatically use responsive first and second person pronouns ("I", "We", "You", "Your", etc.) -Versions of the Assembly Line >= 3.0.0 and Docassemble servers later than 1.4.103 can +Versions of the Assembly Line >= 3.0.0 and docassemble servers later than 1.4.103 can conjugate pronouns in the first and second person as well as the default third-person. This works both for an ALIndividual and an ALPeopleList. @@ -392,7 +392,7 @@ second person pronoun in English): ### More about adapting language based on gender and plurality -[Docassemble's documentation](https://docassemble.org/docs/objects.html#language%20methods) +[docassemble's documentation](https://docassemble.org/docs/objects.html#language%20methods) includes several more comprehensive examples of how to use these functions to automatically use appropriate pronouns. diff --git a/docs/authoring/github.md b/docs/authoring/github.md index 8f25e7cf3..a069392f8 100644 --- a/docs/authoring/github.md +++ b/docs/authoring/github.md @@ -1,36 +1,36 @@ --- id: github -title: Using GitHub with Docassemble +title: Using GitHub with docassemble sidebar_label: "Using GitHub" slug: github --- -We strongly recommend using [GitHub](https://github.com/) with Docassemble. +We strongly recommend using [GitHub](https://github.com/) with docassemble. GitHub is a version control system. It lets you save a snapshot of your interview that you can revert to an earlier version if you need to and see changes over time. GitHub also makes it easier to build interviews with a team, get help, and hand off your code to future interview builders and maintainers. -Here are some more reasons to use GitHub with Docassemble: +Here are some more reasons to use GitHub with docassemble: * Save versions of the interview code you are working on so you can back up to an earlier version/save point if new edits break something -* Collaborate with others to build Docassemble interviews, get help, and hand off your code to future interview builders and maintainers +* Collaborate with others to build docassemble interviews, get help, and hand off your code to future interview builders and maintainers * Share your code with others who might want to build similar interviews * Create branches to work on specific issues, or create multiple branches to keep different issues isolated from each other while you work on them * Track and discuss issues with your code, like tasks, bugs, feature requests, etc. Issues can be assigned, tagged, and attached to commits and pull requests that complete or fix them. * Use projects to gather issues from multiple repositories and organize them on a Kanban-style project board :::info -This page covers how to use GitHub with Docassemble. Refer to the [GitHub documentation](https://docs.github.com/en) if you see unfamiliar vocabulary or have questions about its features. +This page covers how to use GitHub with docassemble. Refer to the [GitHub documentation](https://docs.github.com/en) if you see unfamiliar vocabulary or have questions about its features. ::: ## Workflow -Here is what we recommend for a workflow for using GitHub with the Docassemble playground. Repeat these steps each time you start working on a new task or issue: +Here is what we recommend for a workflow for using GitHub with the docassemble playground. Repeat these steps each time you start working on a new task or issue: -1. Create a new project in your Docassemble playground. Give it a name that describes the work to be done, then pull the **main** branch of your interview from GitHub into the project. +1. Create a new project in your docassemble playground. Give it a name that describes the work to be done, then pull the **main** branch of your interview from GitHub into the project. 2. When you make your first commit from the new project, [commit to a new branch](#commit-your-code) 3. When you finish working on the branch, commit it one last time, then go to the repository in GitHub and [create a pull request](#pull-requests). If you are working with someone on the interview, request a review from them. 4. Once you have resolved any conflicts and any reviewers have signed off, merge the pull request and delete the branch -5. Delete the Docassemble playground project +5. Delete the docassemble playground project 6. Decide on the next task or issue you want to work on and start over at #1 We also shared this workflow in a Document Assembly Line workshop: @@ -40,7 +40,7 @@ We also shared this workflow in a Document Assembly Line workshop:

:::info Workshop Resource -📺 **First Wednesday Workshop:** For comprehensive coverage of GitHub workflows with Docassemble, watch our workshop on [The GitHub-Docassemble workflow](https://suffolklitlab.org/github-docassemble-workflow/). This session includes live demonstrations of branching, merging, and team development workflows specifically designed for Docassemble interview building. +📺 **First Wednesday Workshop:** For comprehensive coverage of GitHub workflows with docassemble, watch our workshop on [The GitHub-docassemble workflow](https://suffolklitlab.org/github-docassemble-workflow/). This session includes live demonstrations of branching, merging, and team development workflows specifically designed for docassemble interview building. ::: ## Collaboration @@ -57,32 +57,32 @@ GitHub is built for collaboration, and tips for collaborating are included throu And here are some things to avoid: * Avoid multiple people working on the same code at the same time, which tends to create merge conflicts -* Avoid using forks, because Docassemble does not handle pull requests from forks very well +* Avoid using forks, because docassemble does not handle pull requests from forks very well ## How to ### Set up the GitHub integration -In order to use GitHub with Docassemble you will need two things: +In order to use GitHub with docassemble you will need two things: -1. Developer privileges on a Docassemble development server with the [GitHub integration configured](https://docassemble.org/docs/installation.html#github). (If you don't have access to a Docassemble development server, [contact us](mailto:litlab@suffolk.edu).) +1. Developer privileges on a docassemble development server with the [GitHub integration configured](https://docassemble.org/docs/installation.html#github). (If you don't have access to a docassemble development server, [contact us](mailto:litlab@suffolk.edu).) 2. A [GitHub](https://github.com/) account. If this is a new account, you may want to [keep your email address private](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address#setting-your-commit-email-address-on-github) and [avoid sharing your email address on commits](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/blocking-command-line-pushes-that-expose-your-personal-email-address). ### Publish your interview to GitHub -The first time you [commit](#commit-your-code) a new interview from the Docassemble playground, it will create a new repository in your GitHub account. +The first time you [commit](#commit-your-code) a new interview from the docassemble playground, it will create a new repository in your GitHub account. :::warning[Check the package name before committing] The first time you commit an interview to GitHub, the package name will become part of the GitHub repository name and URL, and it is difficult to change later on. Use our [package naming guidelines](naming#docassemble-projects-and-packages). ::: -Follow the [Docassemble instructions for publishing an interview package to GitHub](https://docassemble.org/docs/packages.html#github). This will create a repository in your personal GitHub account. +Follow the [docassemble instructions for publishing an interview package to GitHub](https://docassemble.org/docs/packages.html#github). This will create a repository in your personal GitHub account. After you have created the repository, follow [these GitHub instructions to transfer it to your organization](https://docs.github.com/en/repositories/creating-and-managing-repositories/transferring-a-repository). (You must be a member of the organization and have permission to create a repository in the organization.) ### Pull a GitHub repository to the playground -1. Make a new project in the Docassemble playground[^old-project-warning] +1. Make a new project in the docassemble playground[^old-project-warning] 2. In the new project, click on the **Folders** menu and select **Packages** 3. Click the **Pull** button[^github-integration-necessary] 4. Paste the repository URL into the **GitHub URL** field @@ -138,10 +138,10 @@ A commit is a save point. It saves your progress and creates a snapshot of the c GitHub can't help you if you don't use it, so **commit early and often**! -1. In the Docassemble playground, click on the **Folders** menu and select **Packages** +1. In the docassemble playground, click on the **Folders** menu and select **Packages** 2. On the **Packages** screen, review the following fields and update them if necessary: 1. **Author name and email.** These will be included in the public README file. Consider using your organization's name and email, instead. - 2. **Description.** Change the default to something that actually describes the interview. For example: "A Docassemble interview for a Massachusetts 209A Protection from Abuse Order." + 2. **Description.** Change the default to something that actually describes the interview. For example: "A docassemble interview for a Massachusetts 209A Protection from Abuse Order." 3. **URL.** If the interview is live, use the landing-page URL. Learn more about [creating effective landing pages](../get_started/landing_pages.md). 4. **Interview, template, static, and source files.** Only selected files will be uploaded to GitHub. (Hold Control on Windows or Command on macOS while you click to select multiple files.) 5. **README.** Add information for future developers. @@ -153,7 +153,7 @@ GitHub can't help you if you don't use it, so **commit early and often**! That's it! Your commit should show up on GitHub! (If you get an error, check [these troubleshooting tips](#troubleshooting-commit-errors).) :::tip -When you first start working with Docassemble it can be hard to remember to stop and commit. Try creating a daily reminder on your phone. +When you first start working with docassemble it can be hard to remember to stop and commit. Try creating a daily reminder on your phone. ::: You can commit to a branch as often as you want. Developers often wait to commit code until they have it working, but they also might commit broken code so other people can help them troubleshoot, or to save their progress. If you are concerned about ruining working code, make a new branch for the broken code and commit it to that branch. @@ -244,11 +244,11 @@ Changing the name of an interview repository is a multi-step process. For an exa 3. In setup.py in the repository's root directory, search and replace "OldName" with "NewName". 4. Inside the **docassemble** folder, rename the interview folder from **OldName** to **NewName**. -Then you can pull the renamed repository to the Docassemble playground. +Then you can pull the renamed repository to the docassemble playground. -## Troubleshooting errors when committing from Docassemble {#troubleshooting-commit-errors} +## Troubleshooting errors when committing from docassemble {#troubleshooting-commit-errors} -When you get an error committing from Docassemble, it means Docassemble was unable to change anything on GitHub. One of three things is probably going on. +When you get an error committing from docassemble, it means docassemble was unable to change anything on GitHub. One of three things is probably going on. 1. You have technically not made any changes to the code that is actually being pushed to GitHub. 2. You lack [permissions for the repository](https://docs.github.com/en/github/getting-started-with-github/access-permissions-on-github) you are trying to commit to. diff --git a/docs/authoring/name_formats.md b/docs/authoring/name_formats.md index 5f7f42c97..ddaec3912 100644 --- a/docs/authoring/name_formats.md +++ b/docs/authoring/name_formats.md @@ -91,9 +91,9 @@ For a boolean value, use a word or phrase that you can answer with yes or no. Th Use a plural word for a list of things, and a singular word for one thing. **Examples:** `children`, `child` -### Docassemble projects and packages +### docassemble projects and packages -In the Docassemble playground: +In the docassemble playground: * Each project must have a unique name. * Your package name doesn't have to be the same as your project name. diff --git a/docs/authoring/pdf_templates.md b/docs/authoring/pdf_templates.md index 158f985ba..15a21577d 100644 --- a/docs/authoring/pdf_templates.md +++ b/docs/authoring/pdf_templates.md @@ -62,7 +62,7 @@ Do not use: ## Turn off "scroll long text" For all PDF fields, turn off the "scroll long text" option, as this is only -useful if the PDF is viewed on screen. Docassemble interviews usually produce +useful if the PDF is viewed on screen. docassemble interviews usually produce forms that can be printed and filed. ## Use auto-expanding text fields for name fields @@ -104,7 +104,7 @@ If you have a Google, Adobe, Facebook, or Apple account, or if you're willing to ### Adobe Live Cycle If the form was created in Adobe Live Cycle, you will not be able to add form -fields that are compatible with Docassemble. +fields that are compatible with docassemble. To work around this, @@ -134,7 +134,7 @@ with the same field names, for example, in a document bundle, you still may have ## Quality control checklist Many of the below checkbox items can be verified by uploading the PDF to the [Weaver](https://github.com/SuffolkLITLab/docassemble-ALWeaver), -installed on your own Docassemble server. When you upload a PDF to the Weaver, it will try filling in all of the PDF's fields with dummy data, +installed on your own docassemble server. When you upload a PDF to the Weaver, it will try filling in all of the PDF's fields with dummy data, allowing for a quick visual inspection. - [ ] All expected fields have labels and can be completed in the PDF. diff --git a/docs/authoring/weaver_overview.md b/docs/authoring/weaver_overview.md index 9572843a4..0e50e5402 100644 --- a/docs/authoring/weaver_overview.md +++ b/docs/authoring/weaver_overview.md @@ -35,7 +35,7 @@ to edit manually. The Assembly Line Weaver does allow you to reorder screens. However: you will not be able to add **any** logic in the Weaver process. -This is by design. We want you to quickly get to the Docassemble playground +This is by design. We want you to quickly get to the docassemble playground to continue editing your code. ## Before you use the Weaver @@ -92,7 +92,7 @@ you will be asked may change. When you have finished using the Weaver, download your package. This will put a .zip file in the Downloads folder on your computer. -Next, upload this file to the Docassemble playground's `Packages` folder. +Next, upload this file to the docassemble playground's `Packages` folder. ![Folders | Packages ](../assets/playground_packages_menu.png) @@ -107,7 +107,7 @@ Before downloading the package, turn off that behavior: 1. under the General tab, uncheck the option **Open 'safe' files after downloading** ::: -## Example of a page in a Docassemble interview +## Example of a page in a docassemble interview A page might look like this: ![One page of an interview made up of a heading, explanatory text, and the fields](../assets/interview_screen_or_page.png) diff --git a/docs/authoring/writing_review_screen.md b/docs/authoring/writing_review_screen.md index 6cbfdefc0..8b0b33be5 100644 --- a/docs/authoring/writing_review_screen.md +++ b/docs/authoring/writing_review_screen.md @@ -9,7 +9,7 @@ slug: review_screen ## Overview -In Docassemble, a review screen is the way that a user can make changes to their answers. A review screen displays one or more of the user's existing answers along with buttons that let the user edit each choice. +In docassemble, a review screen is the way that a user can make changes to their answers. A review screen displays one or more of the user's existing answers along with buttons that let the user edit each choice. This page is a step-by-step tutorial on how to write a review screen, and covers: diff --git a/docs/coding_style/accessibility.md b/docs/coding_style/accessibility.md index fbb8c5b7f..fe64a2573 100644 --- a/docs/coding_style/accessibility.md +++ b/docs/coding_style/accessibility.md @@ -9,7 +9,7 @@ slug: accessibility Making your guided interviews accessible is first and foremost about making them easy to understand and use. Following [our advice about writing good questions](../style_guide/question_overview) can make your interview overall easier to understand and complete, which helps everyone! -Other parts of web accessibility involve writing the interview in a way that the user's browser and other accessibility tools (like screen readers) can understand. Docassemble [handles many of these things](https://docassemble.org/docs/accessibility.html) for you, but there are some parts that you'll have to address when writing your interview. +Other parts of web accessibility involve writing the interview in a way that the user's browser and other accessibility tools (like screen readers) can understand. docassemble [handles many of these things](https://docassemble.org/docs/accessibility.html) for you, but there are some parts that you'll have to address when writing your interview. To help you find accessibility problems in your interview you can use the [WAVE browser extension](https://wave.webaim.org/extension/), or if you want to check accessibility of your interview automatically, you can use the [ALKiln testing framework](../components/ALKiln/automated_testing.mdx#accessibility). @@ -47,7 +47,7 @@ There should only ever be one `h1` header on a page, and in docassemble, that he ### Header sizes -You might notice that the question header in Docassemble looks smaller than headers in the subquestion. This is because docassemble manually styles the question to +You might notice that the question header in docassemble looks smaller than headers in the subquestion. This is because docassemble manually styles the question to look like an `h3` header, even though it is really a `h1` header. If you want the headers in your subquestion, don't skip header levels until they "look right". Instead, you can manually use HTML and style them as such: ```yaml diff --git a/docs/coding_style/coding_style_overview.md b/docs/coding_style/coding_style_overview.md index bd64a7920..9374de1c5 100644 --- a/docs/coding_style/coding_style_overview.md +++ b/docs/coding_style/coding_style_overview.md @@ -1,6 +1,6 @@ --- id: coding_style_overview -title: Docassemble Coding Style Guide +title: docassemble Coding Style Guide sidebar_label: Coding Style slug: overview --- diff --git a/docs/coding_style/defense.md b/docs/coding_style/defense.md index 6df069375..4e62e90c8 100644 --- a/docs/coding_style/defense.md +++ b/docs/coding_style/defense.md @@ -8,15 +8,15 @@ slug: defense --- :::info Workshop Resource -📺 **First Wednesday Workshop:** For hands-on help with debugging and error resolution, watch our workshop on [Troubleshooting Docassemble interview errors](https://suffolklitlab.org/troubleshooting-docassemble-interview-errors-workshop/). This community Q&A session covers common error patterns, debugging strategies, and prevention techniques. +📺 **First Wednesday Workshop:** For hands-on help with debugging and error resolution, watch our workshop on [Troubleshooting docassemble interview errors](https://suffolklitlab.org/troubleshooting-docassemble-interview-errors-workshop/). This community Q&A session covers common error patterns, debugging strategies, and prevention techniques. ::: -## Use Docassemble lists, dictionaries, and sets, or subclasses +## Use docassemble lists, dictionaries, and sets, or subclasses -Docassemble relies heavily on exceptions for its declarative logic +docassemble relies heavily on exceptions for its declarative logic system. Those work better with the DAObject class and classes that -inherit from it. Docassemble's DAObject class adds an `intrinsicName` -attribute to every object that helps Docassemble track down a question +inherit from it. docassemble's DAObject class adds an `intrinsicName` +attribute to every object that helps docassemble track down a question that is able to define a variable. Where you make uses of lists, dictionaries, or sets, you should @@ -92,8 +92,8 @@ conditions. Make sure that you handle that possibility. When working with APIs, be careful to handle possible failures. Decide what the failure state should be for your end user. Ordinarily, API integrations in -Docassemble are for convenience and your user should be able to continue in some -fashion. You should never drop down to a Docassemble error screen when an +docassemble are for convenience and your user should be able to continue in some +fashion. You should never drop down to a docassemble error screen when an external dependency fails or is unavailable. ## Further reading and sources diff --git a/docs/coding_style/python.md b/docs/coding_style/python.md index 019ad718c..caf5e71f6 100644 --- a/docs/coding_style/python.md +++ b/docs/coding_style/python.md @@ -6,7 +6,7 @@ slug: python --- :::info Workshop Resource -📺 **First Wednesday Workshop:** For help understanding index variables and loop constructs in Docassemble, watch our workshop [Demystifying i and x in Docassemble](https://suffolklitlab.org/demystifying-i-and-x-in-docassemble/). This session clarifies common confusion around indexing and iteration patterns in Docassemble interviews. +📺 **First Wednesday Workshop:** For help understanding index variables and loop constructs in docassemble, watch our workshop [Demystifying i and x in docassemble](https://suffolklitlab.org/demystifying-i-and-x-in-docassemble/). This session clarifies common confusion around indexing and iteration patterns in docassemble interviews. ::: ## Use Python conventions for Python code @@ -15,7 +15,7 @@ In general, we refer to Python's [PEP 8](https://www.python.org/dev/peps/pep-000 ### Highlights of PEP 8 -Docassemble does not force you to write very much Python code. Where you do, however, please +docassemble does not force you to write very much Python code. Where you do, however, please follow Python conventions, listed below. ### Use snake_case for variable names @@ -40,5 +40,5 @@ datatype of the variable. #### Tab width -We use 2 spaces, not 4, for all indentation levels. The Docassemble playground makes it hard to +We use 2 spaces, not 4, for all indentation levels. The docassemble playground makes it hard to edit files that scroll too far horizontally. diff --git a/docs/coding_style/yaml.md b/docs/coding_style/yaml.md index 0fd4cf5c2..c6f3407ea 100644 --- a/docs/coding_style/yaml.md +++ b/docs/coding_style/yaml.md @@ -5,7 +5,7 @@ sidebar_label: Interview files slug: yaml --- -Docassemble interviews are written in +docassemble interviews are written in [YAML](../docassemble_intro/yaml). They may also contain: @@ -27,7 +27,7 @@ See [Python style guide](python.md). ### Use descriptive package names; include state and forum identifiers -For the Docassemble package, use names that help someone understand at a glance +For the docassemble package, use names that help someone understand at a glance what your form does and where it can be used: * include the form **function** and subject area. E.g., `EvictionStay` not @@ -46,7 +46,7 @@ future locate your package on GitHub. ### Avoid spaces in file names; use lowercase letters -Files in your Docassemble package, including YAML files, Python modules, and any +Files in your docassemble package, including YAML files, Python modules, and any static resource files or data sources, should all be be named without spaces. You may choose to use `snake_case` (underscores separating words) or `kebab-case` (hyphens separating words). Using snake case avoids problems with some @@ -88,7 +88,7 @@ already has a copy of the same file. ### When you have multiple files in a single package, give each file a clear prefix While simple interviews have one YAML file, there are three strong reasons to have more than one YAML file in -a single Docassemble package: +a single docassemble package: 1. If one package has multiple, distinct interviews contained within it, perhaps for different audiences, like children, parents, or interested people, or someone filing a complaint or someone answering it. diff --git a/docs/coding_style/yaml_dynamic.md b/docs/coding_style/yaml_dynamic.md index b7d4d7600..93b05abc2 100644 --- a/docs/coding_style/yaml_dynamic.md +++ b/docs/coding_style/yaml_dynamic.md @@ -103,7 +103,7 @@ However, there are common exceptions to this rule: 1. use `needs` on review screens and other blocks that do not automatically trigger referenced variables to trigger `template:` blocks and the like 1. use `sets` with `ALIndividual` blocks that rely on `name_fields()` and - similar fields, where needed for Docassemble to locate the question + similar fields, where needed for docassemble to locate the question ### Use `validation code` carefully diff --git a/docs/coding_style/yaml_interface.md b/docs/coding_style/yaml_interface.md index e2974e55b..ab98813e9 100644 --- a/docs/coding_style/yaml_interface.md +++ b/docs/coding_style/yaml_interface.md @@ -15,7 +15,7 @@ use radio buttons. Use a dropdown menu in situations where: ## Have a "next" or "continue" button on most screens -Docassemble has a "yesno" question type that replaces the "Continue" button +docassemble has a "yesno" question type that replaces the "Continue" button with buttons that immediately move to the next screen. This feature can be disorienting to users with a screen reader and you may lose user trust by having an inconsistent user interface. @@ -70,7 +70,7 @@ content: | Overpayment. ``` -Docassemble has many features that allow you to add help +docassemble has many features that allow you to add help in-context. They include: 1. the [question help button](https://docassemble.org/docs/modifiers.html#help) @@ -101,6 +101,6 @@ distinctive. The risk with this feature is distracting or confusing users. The `field` and `option` help modifiers are both relatively clear and simple to use for field-specific hints and to explain choices that may otherwise not be clear. Custom CSS may make these features slightly more polished than the -stock Docassemble appearance. +stock docassemble appearance. ## \ No newline at end of file diff --git a/docs/coding_style/yaml_structure.md b/docs/coding_style/yaml_structure.md index 49faee3c8..48e6275b9 100644 --- a/docs/coding_style/yaml_structure.md +++ b/docs/coding_style/yaml_structure.md @@ -84,7 +84,7 @@ Adding an id to each question: It is important to be able view the logic of your interview at a glance. The `interview order` block concept is the most powerful way that we have found to -accomplish that goal in Docassemble. +accomplish that goal in docassemble. [Read more about interview order blocks](../docassemble_intro/controlling-interview-order#the-interview-order-block). diff --git a/docs/coding_style/yaml_translation.md b/docs/coding_style/yaml_translation.md index 1bfaba326..e733384b1 100644 --- a/docs/coding_style/yaml_translation.md +++ b/docs/coding_style/yaml_translation.md @@ -32,8 +32,8 @@ language changes. ### Avoid hardcoded string in code - use templates instead Avoid placing literal English text inside code blocks, functions and methods. Instead, -use Docassemble `template` blocks. You should use an `f` string or explicitly -convert `template`s to `str` to avoid certain Docassemble bugs. +use docassemble `template` blocks. You should use an `f` string or explicitly +convert `template`s to `str` to avoid certain docassemble bugs. Example: @@ -47,7 +47,7 @@ code: | list_options = [{'option1': str(my_text_template)}] ``` -Template blocks will become part of the Docassemble XLSX or XLIFF translation +Template blocks will become part of the docassemble XLSX or XLIFF translation file, which makes them the most convenient way to handle text that must be translated. @@ -76,7 +76,7 @@ sections: ### Avoid using the language functions from `pattern.en` in your interview -Docassemble includes very useful features to conjugate verbs, match gender, and +docassemble includes very useful features to conjugate verbs, match gender, and more that are drawn from `pattern.en`, such as the `does_verb` method of a DAList. These are safe to use inside a language-specific template, such as a court form that will always be filed in English. Never use these inside a diff --git a/docs/components/ALDashboard/aldashboard_overview.md b/docs/components/ALDashboard/aldashboard_overview.md index 02adffbc1..a46c1b883 100644 --- a/docs/components/ALDashboard/aldashboard_overview.md +++ b/docs/components/ALDashboard/aldashboard_overview.md @@ -5,7 +5,7 @@ sidebar_label: About ALDashboard slug: /components/ALDashboard/overview --- -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. +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. :::warning This page is a stub @@ -25,7 +25,7 @@ ALDashboard consists of several Python modules, each providing specific function - **validate_docx.py** - DOCX validation utilities - **validate_attachment.py** - Attachment validation tools -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. +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. ## Installation diff --git a/docs/components/ALDashboard/create_package.md b/docs/components/ALDashboard/create_package.md index f0e0a5ceb..0322b122f 100644 --- a/docs/components/ALDashboard/create_package.md +++ b/docs/components/ALDashboard/create_package.md @@ -21,7 +21,7 @@ def create_package_zip(pkgname: str, ``` Given a dictionary of lists, with the keys representing folders and the values -representing a list of DAFiles, create a Python package with Docassemble conventions. +representing a list of DAFiles, create a Python package with docassemble conventions. info: (created by DAInterview.package_info()) license author_name diff --git a/docs/components/ALDashboard/project_maintenance.md b/docs/components/ALDashboard/project_maintenance.md index 31264bf87..56cd1c59b 100644 --- a/docs/components/ALDashboard/project_maintenance.md +++ b/docs/components/ALDashboard/project_maintenance.md @@ -25,11 +25,11 @@ title: ALDashboard.project_maintenance def get_package_names(server_name: str) -> List[str] ``` -Fetches the JSON file from the given Docassemble server and extracts package names. +Fetches the JSON file from the given docassemble server and extracts package names. **Arguments**: -- `server_name` _str_ - Name or IP address of the Docassemble server. +- `server_name` _str_ - Name or IP address of the docassemble server. **Returns**: @@ -76,12 +76,12 @@ def process_packages_and_add_tag(server_name: str, token: str, org_name: str, tag: str) -> None ``` -Fetches package names from a Docassemble server, transforms them into repository names, +Fetches package names from a docassemble server, transforms them into repository names, and adds a specified tag to each repository. **Arguments**: -- `server_name` _str_ - Name or IP address of the Docassemble server. +- `server_name` _str_ - Name or IP address of the docassemble server. - `token` _str_ - GitHub Personal Access Token. - `org_name` _str_ - Name of the GitHub organization. - `tag` _str_ - Tag to be added to each repository. diff --git a/docs/components/ALKiln/automated_testing.mdx b/docs/components/ALKiln/automated_testing.mdx index c72e7c1c2..73cbe53db 100644 --- a/docs/components/ALKiln/automated_testing.mdx +++ b/docs/components/ALKiln/automated_testing.mdx @@ -10,7 +10,7 @@ import { Anchor } from '/docs/react_components/\Anchor.js'; :::info Workshop Resource -📺 **First Wednesday Workshop:** For a comprehensive guide to implementing automated testing with ALKiln, watch our workshop [Building resilient Docassemble interviews with ALKiln automated testing](https://suffolklitlab.org/building-resilient-docassemble-interviews-with-alkiln-automated-testing/). This session covers test setup, best practices, and debugging techniques for robust interview development. +📺 **First Wednesday Workshop:** For a comprehensive guide to implementing automated testing with ALKiln, watch our workshop [Building resilient docassemble interviews with ALKiln automated testing](https://suffolklitlab.org/building-resilient-docassemble-interviews-with-alkiln-automated-testing/). This session covers test setup, best practices, and debugging techniques for robust interview development. ::: **Any docassemble package can use ALKiln**, though it does have special features created especially for projects using AssemblyLine. Give us feedback and propose ideas by making issues at https://github.com/SuffolkLITLab/ALKiln/issues. @@ -73,7 +73,7 @@ dispatch: You will need to have a GitHub account that has permissions to edit the GitHub repository that you want to test. 1. Prepare your repository or organization for testing using [ALKiln's test setup interview](https://apps-dev.suffolklitlab.org/start/test-setup). Follow the instructions there to add new code to your repository, including a new "workflow" file. This can take over 30 minutes if you're unfamiliar with GitHub and docassemble API keys. -1. In Docassemble, make a new Project and pull in the package's updated code. +1. In docassemble, make a new Project and pull in the package's updated code. 1. In the Project's Sources folder, add files with a `.feature` extension to write tests. You might already have an example test in that folder if you chose to create one during the ALKiln setup interview. 1. Commit the new files to GitHub to trigger the tests to run. 1. [See the results](#see-github-test-results). diff --git a/docs/components/ALKiln/security.mdx b/docs/components/ALKiln/security.mdx index f735a465e..1c7e003a8 100644 --- a/docs/components/ALKiln/security.mdx +++ b/docs/components/ALKiln/security.mdx @@ -536,7 +536,7 @@ With most updates, you can usually wait a little while to see if there are any b [Clear out the testing server and start a new docker container from scratch](https://docassemble.org/docs/docker.html#upgrading) when there are security upgrades. Then run all your tests before upgrading your production server too. -Docassemble's Docker image gets updated occasionally. You can wait a little while to see if there are any bugs that come up, but generally keep up to date with those as much as you can, especially when there are security fixes. +docassemble's Docker image gets updated occasionally. You can wait a little while to see if there are any bugs that come up, but generally keep up to date with those as much as you can, especially when there are security fixes. Even if there is not a security-related update, it is good to stress test your server setup. Since you might have to suddenly start a new Docker container at unexpected times because of system failures, it is a good idea to do this every now and then anyway to make sure your system can handle recovering from that kind of event and see if complications come up. diff --git a/docs/components/ALKiln/setup.mdx b/docs/components/ALKiln/setup.mdx index e415a3ea1..d358db367 100644 --- a/docs/components/ALKiln/setup.mdx +++ b/docs/components/ALKiln/setup.mdx @@ -38,7 +38,7 @@ Maybe not. For example, if you have a GitHub repository and it already has a ".g - **People who only write tests:** Skip this and see the [documentation on writing tests](writing_tests.mdx). - **GitHub repository or organization managers or admins:** This guide might be useful to you. -- **Docassemble server managers or admins:** This guide might be useful to you. +- **docassemble server managers or admins:** This guide might be useful to you. - ALKiln errors and warnings -- Docassemble errors and warnings +- docassemble errors and warnings - Errors and warnings from the third-party libraries that ALKiln uses diff --git a/docs/docassemble_intro/theming-docassemble.md b/docs/docassemble_intro/theming-docassemble.md index fdda331dd..14ea614d3 100644 --- a/docs/docassemble_intro/theming-docassemble.md +++ b/docs/docassemble_intro/theming-docassemble.md @@ -4,17 +4,17 @@ title: Applying custom themes sidebar_label: Applying custom themes --- -## Customizing Docassemble's visual appearance +## Customizing docassemble's visual appearance [Themes](https://docassemble.org/docs/initial.html#bootstrap%20theme) can be used to control -Docassemble interviews': +docassemble interviews': - colors - fonts - button appearance - size and shape of inputs -You can use an off the shelf theme, but note that as of this writing Docassemble is built +You can use an off the shelf theme, but note that as of this writing docassemble is built around Bootstrap 5.2. Most themes you find online may be Bootstrap 4 or earlier. Using a theme from an older version of Bootstrap may result in visual and other interface glitches. @@ -25,7 +25,7 @@ options that are configurable with css, you can: 1. build one from Bootstrap 5 source 1. start with a theme generator tool like [bootstrap.build](https://bootstrap.build/) - and in some cases, add some custom CSS to make it work with Docassemble. + and in some cases, add some custom CSS to make it work with docassemble. Using bootstrap.build is the simplest option for most authors. @@ -41,7 +41,7 @@ Using bootstrap.build is the simplest option for most authors. "bootstrap.min.css" option. Rename this theme to be more specific. Optionally, download the `_variables.scss` file so that you can easily load and adjust your settings in future. -Add this theme to your Docassemble playground using the Folders | Static menu. +Add this theme to your docassemble playground using the Folders | Static menu. Next, you will need to make a small adjustment to the theme generated by bootstrap.build. Copy and paste the code below into the `bootstrap.min.css` file (or your new file name). @@ -63,8 +63,8 @@ Copy and paste the code below into the `bootstrap.min.css` file (or your new fil ``` We have identified the small patches above that are required to use Bootstrap.build to make -a Docassemble theme, but you may run into more. The safest way to create a theme for -Docassemble is by building it from source, following the instructions below. +a docassemble theme, but you may run into more. The safest way to create a theme for +docassemble is by building it from source, following the instructions below. ### Creating a custom theme from source instead of with a theme generator @@ -139,12 +139,12 @@ npm run css-compile ``` Your new `custom.css` file is in the -~/bootstrap-5.1.3/dist/css` directory. Copy this file to your Docassemble +~/bootstrap-5.1.3/dist/css` directory. Copy this file to your docassemble `static` folder and reference it as a `bootstrap theme`. ### Using custom fonts in the frontend -You can use custom webfonts with Docassemble, just like you can with any other web +You can use custom webfonts with docassemble, just like you can with any other web product. This [Mozilla guide about web @@ -156,12 +156,12 @@ If you do not already have a .woff or .woff2 file but you do have a TrueType one with a [free online web font tool](https://www.fontsquirrel.com/tools/webfont-generator). -1. Once you have a .woff file, upload it to the /static folder of a Docassemble playground. +1. Once you have a .woff file, upload it to the /static folder of a docassemble playground. 1. Add an `@font-face` directive to your bootstrap.css file (or a separate CSS file that you reference in the `features` block of your interview) You cannot include Mako tags in your CSS file, so in order to use the new font face, you should -add it to a Docassemble package and then install the package on your server. +add it to a docassemble package and then install the package on your server. Example: @@ -175,14 +175,14 @@ Example: } ``` -In the example above, MyTheme is a Docassemble package that is installed +In the example above, MyTheme is a docassemble package that is installed server-wide. my_font is both the name of a web font and the name of the WOFF file. ### Using custom fonts when creating PDF files from DOCX templates If you would like to use a font **other than** the Microsoft fonts popular in the late 1990s-2000 era (Arial, Times New Roman, Courier) then you will need to -install the fonts on your Docassemble server. +install the fonts on your docassemble server. Make sure that you have a license for each font you want to install. diff --git a/docs/docassemble_intro/working-with-docx.md b/docs/docassemble_intro/working-with-docx.md index 8a796db39..bcea72466 100644 --- a/docs/docassemble_intro/working-with-docx.md +++ b/docs/docassemble_intro/working-with-docx.md @@ -39,7 +39,7 @@ You can copy and paste the text above right into the Word file. Name the file `hello_world.docx`. Upload it to your playground using the Folders | Templates area of the playground. -Next, make a new interview in your Docassemble playground that looks like this: +Next, make a new interview in your docassemble playground that looks like this: ```yaml --- @@ -61,7 +61,7 @@ Save and run the interview, and see what you get. Our interview has a question for one variable: `user_name`. Inside the docx file, we put the variable name inside curly brackets, like this: `{{ user_name }}`. -Docassemble replaced `{{ user_name }}` with the text we entered when we ran the interview. +docassemble replaced `{{ user_name }}` with the text we entered when we ran the interview. Notice that the `{{ }}` is pretty similar to what we did in the Hello, World exercise. This syntax is called [Jinja2](jinja2.md). The big difference is in a Docx we use two curly @@ -82,7 +82,7 @@ makes. ## Mail Merge can't do **that** What if we wanted to include some optional text in our template? It's pretty common -to want different versions of a document for different scenarios. Docassemble of +to want different versions of a document for different scenarios. docassemble of course allows you to use conditional text inside your Docx template. Create a Word document with the text below. You can copy and paste the @@ -149,7 +149,7 @@ headings, bold, and so on? What about changing the format of the `{{ user_name } 1. The [attachment](https://docassemble.org/docs/documents.html#attachment) block 1. [Docx Templates](https://docassemble.org/docs/documents.html#docx%20template%20file) -1. [Docassemble tutorial](https://docassemble.org/docs/helloworld.html) +1. [docassemble tutorial](https://docassemble.org/docs/helloworld.html) 1. [Jinja reference](https://jinja.palletsprojects.com/en/2.11.x/) (this is similar but not the exact syntax used in Docasssemble) 1. [Docx-template Jinja reference](https://docxtpl.readthedocs.io/en/latest/#jinja2-like-syntax) diff --git a/docs/docassemble_intro/yaml.md b/docs/docassemble_intro/yaml.md index dac13fc0f..e9e4ed28e 100644 --- a/docs/docassemble_intro/yaml.md +++ b/docs/docassemble_intro/yaml.md @@ -4,7 +4,7 @@ title: Question files (YAML) sidebar_label: Question files (YAML) --- -When Jonathan Pyle created Docassemble, he chose to use the [YAML](https://en.wikipedia.org/wiki/YAML) file format as the main way to represent the contents of an interview. When writing a Docassemble interview, it can be helpful to understand what YAML is, which conventions are Docassemble standards that overlay YAML, and how the different components of a Docassemble interview are represented in YAML. +When Jonathan Pyle created docassemble, he chose to use the [YAML](https://en.wikipedia.org/wiki/YAML) file format as the main way to represent the contents of an interview. When writing a docassemble interview, it can be helpful to understand what YAML is, which conventions are docassemble standards that overlay YAML, and how the different components of a docassemble interview are represented in YAML. YAML, which stands for Yet Another Markup Language (or YAML Ain't a Markup Language), is a standardized way for a computer program to save information to a file. Most commonly, this is configuration data: a way to store a list of preferences and settings that relate to a program or web application. One of the goals of YAML is to be human readable. That means a minimum of clutter. YAML stands on the shoulders of previous file formats, such as [INI](https://en.wikipedia.org/wiki/INI_file), [XML](https://en.wikipedia.org/wiki/XML), and [JSON](https://en.wikipedia.org/wiki/JSON), all of which make different trade-offs of readability and conciseness. The structures of the different formats also each tend to represent different kinds of data better. @@ -27,7 +27,7 @@ Block 1 --- Block 2 ``` -The name document is confusing when applied to a Docassemble interview's file, since each interview will contain multiple `documents`, but it's part of the YAML standard. Just mentally replace the word `document` with block if you need to refer to the YAML standard, and you'll be fine. +The name document is confusing when applied to a docassemble interview's file, since each interview will contain multiple `documents`, but it's part of the YAML standard. Just mentally replace the word `document` with block if you need to refer to the YAML standard, and you'll be fine. ### Dictionaries A [dictionary](https://en.wikipedia.org/wiki/Associative_array) is a kind of data structure in computer programming. Just like the standard definition, the point of a dictionary is that you have multiple entries (the definitions), and you can look up each entry with a keyword. One thing special about the computer kind of dictionary is that the order of entries doesn't matter. The only thing guaranteed is that the keyword (or key) retrieves the linked definition. In YAML, a dictionary entry is a key followed by a :, and then a value or definition. In the example below, the keyword is “question” and the value is “What is your name?” @@ -37,7 +37,7 @@ question: What is your name? answer: Jane Smith ``` -Throughout the documentation, Docassemble uses the term `specifier` for a dictionary key that has a special meaning inside the interview format. There are many such specifiers, with question, subquestion, fields, and code being specifiers you will use right away. +Throughout the documentation, docassemble uses the term `specifier` for a dictionary key that has a special meaning inside the interview format. There are many such specifiers, with question, subquestion, fields, and code being specifiers you will use right away. ### Lists @@ -51,7 +51,7 @@ A [list](https://en.wikipedia.org/wiki/List_(abstract_data_type)), which is simi ### Data -YAML files can also contain data: the values that are stored in a list or dictionary. The most common kind of data is text data. Optionally, text can be surrounded by quotes. This might be needed if your text contains some of the special characters, such as a colon, but more often you leave quotes off. There is one special way to represent data that you should use often inside a Docassemble-flavored YAML file, which is the line continuation indicator or vertical pipe separator (|). Inside a dictionary's value, the vertical pipe separator tells YAML that everything that follows on the next indented line is going to be text, and that the text may flow on multiple lines and can contain special characters. +YAML files can also contain data: the values that are stored in a list or dictionary. The most common kind of data is text data. Optionally, text can be surrounded by quotes. This might be needed if your text contains some of the special characters, such as a colon, but more often you leave quotes off. There is one special way to represent data that you should use often inside a docassemble-flavored YAML file, which is the line continuation indicator or vertical pipe separator (|). Inside a dictionary's value, the vertical pipe separator tells YAML that everything that follows on the next indented line is going to be text, and that the text may flow on multiple lines and can contain special characters. ```yaml --- @@ -61,17 +61,17 @@ question: | needs to be indented to the same level underneath the dictionary key. ``` -Text is text, and as the saying goes, what you see is what you get. However, the text inside a Docassemble YAML file can almost always be formatted using Markdown, which is another standard. +Text is text, and as the saying goes, what you see is what you get. However, the text inside a docassemble YAML file can almost always be formatted using Markdown, which is another standard. -I want to discuss [Markdown](markdown.md) here only to point out that an interview file can contain Markdown, but as far as YAML goes, its all plain text. Docassemble looks for Markdown tags in the text and applies the formatting where it's appropriate. +I want to discuss [Markdown](markdown.md) here only to point out that an interview file can contain Markdown, but as far as YAML goes, its all plain text. docassemble looks for Markdown tags in the text and applies the formatting where it's appropriate. -In addition to text blocks that may or not be formatted with Markdown, Docassemble's YAML files typically contain blocks of instructions called code blocks (which might be called scripts in a different platform). +In addition to text blocks that may or not be formatted with Markdown, docassemble's YAML files typically contain blocks of instructions called code blocks (which might be called scripts in a different platform). ### Code blocks -Code blocks are just text data as far as the YAML file format is concerned. But Docassemble will interpret the text as Python code. Python is one of the most popular programming languages in the world due to its simple and expressive syntax and ease of learning, as well as its power and extensive library of “packages” that make it easy to use functionality created by other people. +Code blocks are just text data as far as the YAML file format is concerned. But docassemble will interpret the text as Python code. Python is one of the most popular programming languages in the world due to its simple and expressive syntax and ease of learning, as well as its power and extensive library of “packages” that make it easy to use functionality created by other people. -In Docassemble's YAML files, you can mix Python code with your interview file with the code: specifier, like this: +In docassemble's YAML files, you can mix Python code with your interview file with the code: specifier, like this: ```yaml --- @@ -82,25 +82,25 @@ code: | my_variable = 1 + 3 ``` -You might notice that a Python code block in Docassemble is really a special kind of dictionary, one that starts with the keyword “code”. This lets Docassemble know that the text that follows will interpreted as instructions rather than another purpose. Code blocks are great for instructions and conditional logic that are related to the flow of the interview. More complex code is better contained inside a regular Python module, or .py file. Python code blocks can contain comments, but YAML itself can contain comments, too. +You might notice that a Python code block in docassemble is really a special kind of dictionary, one that starts with the keyword “code”. This lets docassemble know that the text that follows will interpreted as instructions rather than another purpose. Code blocks are great for instructions and conditional logic that are related to the flow of the interview. More complex code is better contained inside a regular Python module, or .py file. Python code blocks can contain comments, but YAML itself can contain comments, too. ### YAML Comments -The final type of YAML contents that you should be aware of are comments. Comments begin with a # symbol and are ignored by Docassemble. Like the other contents of a YAML file, YAML comments need to follow the same indentation rules. Here's an example: +The final type of YAML contents that you should be aware of are comments. Comments begin with a # symbol and are ignored by docassemble. Like the other contents of a YAML file, YAML comments need to follow the same indentation rules. Here's an example: ```yaml --- question: | - # This is a heading because Docassemble thinks it is Markdown + # This is a heading because docassemble thinks it is Markdown # This is a comment because it is not indented as part of the question: key's data field. ``` -YAML, like Python, does not have multi-line comments. Each line needs to start with a #. Docassemble does have its own special [comment](https://docassemble.org/docs/modifiers.html#comment) `specifier` that can extend over multiple lines. +YAML, like Python, does not have multi-line comments. Each line needs to start with a #. docassemble does have its own special [comment](https://docassemble.org/docs/modifiers.html#comment) `specifier` that can extend over multiple lines. When writing an interview file, use comments liberally. They can make your logic easier to read, either for another developer, or more often, you in a few months or a year. ### Nesting data structures -Unlike the INI format, but like JSON and XML, a YAML datastructure can itself contain additional datastructures. For example, each item in a list could be a dictionary, or vice versa. Nesting is done by indentation, with no true limit to the number of indentation levels. The most common indentation for Docassemble's YAML file is two spaces. +Unlike the INI format, but like JSON and XML, a YAML datastructure can itself contain additional datastructures. For example, each item in a list could be a dictionary, or vice versa. Nesting is done by indentation, with no true limit to the number of indentation levels. The most common indentation for docassemble's YAML file is two spaces. ```yaml --- @@ -112,13 +112,13 @@ dictionary_key1: - Item 2 ``` -This nesting is actually quite common in Docassemble's interview files. For example, fields: is a dictionary key that contains a list of dictionaries. Sometimes Docassemble allows you to use either a dictionary or a list as the contents of a specifier. Whenever this is true, make sure you understand the major difference: a list has an order that is guaranteed, while a dictionary does not. +This nesting is actually quite common in docassemble's interview files. For example, fields: is a dictionary key that contains a list of dictionaries. Sometimes docassemble allows you to use either a dictionary or a list as the contents of a specifier. Whenever this is true, make sure you understand the major difference: a list has an order that is guaranteed, while a dictionary does not. ## Digging deeper: the fields specifier -Because Docassemble's fields specifier behaves differently to the regular YAML dictionary keys that they resemble, I wanted to take a minute to look at this specifier a bit closer. +Because docassemble's fields specifier behaves differently to the regular YAML dictionary keys that they resemble, I wanted to take a minute to look at this specifier a bit closer. -Here's a typical Docassemble question block with a fields specifier: +Here's a typical docassemble question block with a fields specifier: ```yaml --- @@ -134,7 +134,7 @@ Let's break this down and label the different components. The specifier 1) `question` itself is a dictionary key, followed by text (which could have had Markdown formatting if we desired). 2) `fields` is also a dictionary key. The dashes (3) and (4) represent items in a list that is indented underneath the fields specifier. (5) `First name` and (6) `Last name` represent dictionary keys again, while (7) `client.name.first` and (8) `client.name.last` are values. -Wait a second. Doesn't it make more sense to think of the label (First name, Last name) as a value, while the variable names (client.name.first and client.name.last) are more akin to dictionary keys? Yes, it does. That's exactly how they are used inside Docassemble itself. However, in this special case, Docassemble does the magic to allow you to write your field labels in a more natural and human-readable order. This is one example where adhering too closely to the YAML format could be a bit confusing. +Wait a second. Doesn't it make more sense to think of the label (First name, Last name) as a value, while the variable names (client.name.first and client.name.last) are more akin to dictionary keys? Yes, it does. That's exactly how they are used inside docassemble itself. However, in this special case, docassemble does the magic to allow you to write your field labels in a more natural and human-readable order. This is one example where adhering too closely to the YAML format could be a bit confusing. ## Keep reading diff --git a/docs/get_started/al_project_architecture.md b/docs/get_started/al_project_architecture.md index ee448f63f..0b0083e46 100644 --- a/docs/get_started/al_project_architecture.md +++ b/docs/get_started/al_project_architecture.md @@ -15,12 +15,12 @@ Below is a snapshot of the Project's overall architecture as of **June 2022**. W | Component | Description | GitHub Repository | |:----------|:------------|:------------------| -| [AssemblyLine](https://github.com/suffolkLITLab/docassemble-AssemblyLine) | Utility library that makes it easier to use certain Docassemble features in an interview. | [SuffolkLITLab/docassemble-AssemblyLine](https://github.com/SuffolkLITLab/docassemble-AssemblyLine) | +| [AssemblyLine](https://github.com/suffolkLITLab/docassemble-AssemblyLine) | Utility library that makes it easier to use certain docassemble features in an interview. | [SuffolkLITLab/docassemble-AssemblyLine](https://github.com/SuffolkLITLab/docassemble-AssemblyLine) | | [ALWeaver](../authoring/weaver_overview.md) | Helps create a draft interviews from PDF and DOCX forms. | [suffolkLITLab/docassemble-ALWeaver](https://github.com/SuffolkLITLab/docassemble-ALWeaver) | -| [ALToolbox](https://github.com/SuffolkLITLab/docassemble-ALToolbox) | Utility functions and components that are used in AssemblyLine but that can be easily used by Docassemble developers who use other platforms. | [SuffolkLITLab/docassemble-ALToolbox](https://github.com/SuffolkLITLab/docassemble-ALToolbox) | +| [ALToolbox](https://github.com/SuffolkLITLab/docassemble-ALToolbox) | Utility functions and components that are used in AssemblyLine but that can be easily used by docassemble developers who use other platforms. | [SuffolkLITLab/docassemble-ALToolbox](https://github.com/SuffolkLITLab/docassemble-ALToolbox) | | [ALKiln](../components/ALKiln/intro.mdx) | Automated testing framework that acts like a user, following your instructions to do things like fill in fields, upload files, sign in, and check your PDFs for accuracy. | [SuffolkLITLab/ALKiln](https://github.com/SuffolkLITLab/ALKiln) | -| [ALDashboard](/docs/components/ALDashboard/overview) | A collection of tools to help administer a Docassemble server and debug interviews. | [SuffolkLITLab/docassemble-ALDashboard](https://github.com/SuffolkLITLab/docassemble-ALDashboard) | -| [ALRecipes](../components/ALRecipes/alrecipes_overview.md) | Examples for Document Assembly Line interviews, plus generic Docassemble examples addressing specific needs. | [SuffolkLITLab/docassemble-ALRecipes](https://github.com/SuffolkLITLab/docassemble-ALRecipes) | +| [ALDashboard](/docs/components/ALDashboard/overview) | A collection of tools to help administer a docassemble server and debug interviews. | [SuffolkLITLab/docassemble-ALDashboard](https://github.com/SuffolkLITLab/docassemble-ALDashboard) | +| [ALRecipes](../components/ALRecipes/alrecipes_overview.md) | Examples for Document Assembly Line interviews, plus generic docassemble examples addressing specific needs. | [SuffolkLITLab/docassemble-ALRecipes](https://github.com/SuffolkLITLab/docassemble-ALRecipes) | | [InterviewStats](https://github.com/SuffolkLITLab/docassemble-InterviewStats/) | A docassemble interview that lets you view statistics from other saved interview responses. | [SuffolkLITLab/InterviewStats/docassemble-InterviewStats](https://github.com/SuffolkLITLab/docassemble-InterviewStats/) | | Documentation | This website. | [SuffolkLITLab/AssemblyLine-docs](https://github.com/SuffolkLITLab/AssemblyLine-docs) | | E-Filing Proxy Server | | [SuffolkLITLab/EfileProxyServer](https://github.com/SuffolkLITLab/EfileProxyServer) | @@ -30,7 +30,7 @@ Below is a snapshot of the Project's overall architecture as of **June 2022**. W ### Massachusetts -Due to the LIT Lab's extensive work with the Massachusetts Appeals Court, these repositories help model court, venue, and jurisdiction information in Docassemble for Massachusetts and as a possible starting point in other jurisdictions. +Due to the LIT Lab's extensive work with the Massachusetts Appeals Court, these repositories help model court, venue, and jurisdiction information in docassemble for Massachusetts and as a possible starting point in other jurisdictions. 1. [ALMassachusetts](https://github.com/suffolkLITLab/docassemble-ALMassachusetts) 1. [MassAccess](https://github.com/suffolkLITLab/docassemble-MassAccess) diff --git a/docs/get_started/beginners_guide.md b/docs/get_started/beginners_guide.md index 5adbf78a5..5c265125b 100644 --- a/docs/get_started/beginners_guide.md +++ b/docs/get_started/beginners_guide.md @@ -1,21 +1,21 @@ --- id: beginners_guide -title: Learn to build Docassemble interviews +title: Learn to build docassemble interviews sidebar_label: Beginner's guide slug: beginners_guide --- -If you have never used Docassemble before, you are on the right page! Below are a quick introduction, an in-depth interview builder training course, and additional resources. +If you have never used docassemble before, you are on the right page! Below are a quick introduction, an in-depth interview builder training course, and additional resources. :::tip -You will need access to a [Docassemble playground](https://docassemble.org/docs/playground.html), but if you don't have one you can use ours! Register an account on the [LIT Lab Docassemble development server](https://apps-dev.suffolklitlab.org/user/register), then [email us](mailto:litlab@suffolk.edu) and ask for developer privileges. +You will need access to a [docassemble playground](https://docassemble.org/docs/playground.html), but if you don't have one you can use ours! Register an account on the [LIT Lab docassemble development server](https://apps-dev.suffolklitlab.org/user/register), then [email us](mailto:litlab@suffolk.edu) and ask for developer privileges. ::: ## Quick introduction -[The Hello, World exercise](#do-the-hello-world-exercise) is a quick, friendly introduction to Docassemble. +[The Hello, World exercise](#do-the-hello-world-exercise) is a quick, friendly introduction to docassemble. -After doing the exercise, [watch a demonstration of the Weaver](https://www.youtube.com/live/1zF_omoCm1c?si=u9MqDGm_1G3iAH7t&t=1595), a Document Assembly Line tool for quickly turning prepared forms into draft Docassemble interviews. The code generated by the Weaver is not a finished interview; it is a starting point intended for further editing. +After doing the exercise, [watch a demonstration of the Weaver](https://www.youtube.com/live/1zF_omoCm1c?si=u9MqDGm_1G3iAH7t&t=1595), a Document Assembly Line tool for quickly turning prepared forms into draft docassemble interviews. The code generated by the Weaver is not a finished interview; it is a starting point intended for further editing. Finally, [review the interview project management page](#review-the-interview-project-management-guide) to get an idea of what an interview-building project is like. @@ -30,4 +30,4 @@ To join the Document Assembly Line community, just [email us](mailto:litlab@suff ## Additional resources - [An interview-building guide for "non-techies"](https://www.legalservicesvt.org/building-legal-aid-guided-interviews-with-docassemble) from Legal Services Vermont -- [Legal Tech Class: Introduction to Docassemble](https://projects.suffolklitlab.org/legal-tech-class/docs/introduction-to-docassemble/) by Quinten Steenhuis \ No newline at end of file +- [Legal Tech Class: Introduction to docassemble](https://projects.suffolklitlab.org/legal-tech-class/docs/introduction-to-docassemble/) by Quinten Steenhuis \ No newline at end of file diff --git a/docs/get_started/development_roadmap.md b/docs/get_started/development_roadmap.md index 092040c64..b8871029a 100644 --- a/docs/get_started/development_roadmap.md +++ b/docs/get_started/development_roadmap.md @@ -47,10 +47,10 @@ Here are our current priorities, from our February 2026 roadmapping meeting: - Volunteer coordination - **Completed** API access to interview snapshot data -### Docassemble hosting +### docassemble hosting -- Docassemble hosting infrastructure upgrades -- Docassemble hosting support +- docassemble hosting infrastructure upgrades +- docassemble hosting support - **Completed** New DevOps engineer onboarding ### E-filing diff --git a/docs/get_started/installation.md b/docs/get_started/installation.md index 2bc94c0fe..b8eb571e5 100644 --- a/docs/get_started/installation.md +++ b/docs/get_started/installation.md @@ -6,7 +6,7 @@ slug: installation --- Before you get started, make sure that you have [installed -Docassemble](../admin_guide_docassemble/setup-server) +docassemble](../admin_guide_docassemble/setup-server) on a server that you maintain. Installing the Assembly Line covers the following basic steps: @@ -32,7 +32,7 @@ It will help you: To install ALDashboard: -1. visit the "Package Management" menu on your Docassemble server when you are +1. visit the "Package Management" menu on your docassemble server when you are logged in as a server administrator 1. Type `docassemble.ALDashboard` into the input box labeled `Package on PyPI` ![Package on PyPI](../assets/installation_package_on_pypi.png) @@ -41,7 +41,7 @@ To install ALDashboard: ## Run the installation script Once ALDashboard is successfully installed, edit this link to replace -`YOUR_SERVER` with the URL to your own Docassemble server and visit it. +`YOUR_SERVER` with the URL to your own docassemble server and visit it. ``` https://YOURSERVER.com/start/ALDashboard/menu @@ -78,7 +78,7 @@ configuration later. is a docassemble package that includes an example of how to modify questions and customize them for your own jurisdiction or organization. -To use this package, [pull it into your own Docassemble playground](https://docassemble.org/docs/playground.html#packages). +To use this package, [pull it into your own docassemble playground](https://docassemble.org/docs/playground.html#packages). Next, [follow our guide](../components/ALThemeTemplate/althemetemplate_overview.md) to edit the YAML files and add a custom CSS theme to fit your own organization's needs. @@ -88,7 +88,7 @@ Select the files that you customized and push them to your own Github repository :::info Copy, do not fork It is important to copy and create a new package. Do not -fork the ALThemeTemplate package as Docassemble makes it +fork the ALThemeTemplate package as docassemble makes it challenging to rename a package. ::: @@ -132,8 +132,8 @@ package: ### Increase nginx timeouts to 5 minutes -Sometimes, long-running Docassemble processes can "timeout." The default -experience in Docassemble is to show the server's built-in error page, +Sometimes, long-running docassemble processes can "timeout." The default +experience in docassemble is to show the server's built-in error page, which can be confusing for your end user. We recommend that you increase the nginx timeout for uwsgi from 60 seconds diff --git a/docs/get_started/intro.md b/docs/get_started/intro.md index 93b940829..034e359f3 100644 --- a/docs/get_started/intro.md +++ b/docs/get_started/intro.md @@ -5,7 +5,7 @@ sidebar_label: Introduction slug: /get_started --- -The Document Assembly Line helps people build open-source access-to-justice tools and resources for court forms, online guided interviews, and e-filing. We also provide affordable Docassemble hosting and e-filing tools for courts and legal aid organizations. +The Document Assembly Line helps people build open-source access-to-justice tools and resources for court forms, online guided interviews, and e-filing. We also provide affordable docassemble hosting and e-filing tools for courts and legal aid organizations. The Document Assembly Line is supported by the [Legal Innovation and Technology Lab (LIT Lab)](https://suffolklitlab.org/) at [Suffolk University Law School](https://www.suffolk.edu/law/) and a community of courts, orgs, and volunteers. [Our community goals and practices](/docs/get_started/community_practices.md) describe the collaborative environment we aim to foster. @@ -21,17 +21,17 @@ This short, 3-minute video by David Colarusso and Quinten Steenhuis explains how

-The LIT Lab gathered more than 200 volunteers from around the world with the goal of making it easier to build online guided interviews with Docassemble. The initial tools included: +The LIT Lab gathered more than 200 volunteers from around the world with the goal of making it easier to build online guided interviews with docassemble. The initial tools included: -* The core [AssemblyLine tools](https://github.com/SuffolkLITLab/docassemble-AssemblyLine), to make it easier to use key Docassemble features -* The [the Weaver](../authoring/weaver_overview.md), a tool for converting existing PDF and DOCX court forms into draft Docassemble interviews in as little as one hour +* The core [AssemblyLine tools](https://github.com/SuffolkLITLab/docassemble-AssemblyLine), to make it easier to use key docassemble features +* The [the Weaver](../authoring/weaver_overview.md), a tool for converting existing PDF and DOCX court forms into draft docassemble interviews in as little as one hour * A [question library](../style_guide/question_library/names.md) of pre-built, commonly used, accessible questions, vetted by experts and translated into at least 5 languages -* An [open-source, non-profit e-filing service provider (EFSP)](components/EFSPIntegration/efsp_overview.md) for integrating Docassemble interviews with e-filing management systems +* An [open-source, non-profit e-filing service provider (EFSP)](components/EFSPIntegration/efsp_overview.md) for integrating docassemble interviews with e-filing management systems * A [style guide](../style_guide/question_style_overview.md) for interview questions that are easy to read and answer -The Document Assembly Line has evolved into a community of courts and legal aid organizations building online guided interviews using Docassemble and the AssemblyLine tools. +The Document Assembly Line has evolved into a community of courts and legal aid organizations building online guided interviews using docassemble and the AssemblyLine tools. -We continue to update and expand the AssemblyLine tools and resources. In 2024, we also began offering affordable Docassemble hosting and e-filing tools for courts and legal aid organizations. +We continue to update and expand the AssemblyLine tools and resources. In 2024, we also began offering affordable docassemble hosting and e-filing tools for courts and legal aid organizations. ## See the Document Assembly Line in action @@ -39,13 +39,13 @@ You can see online guided interviews from the community, Suffolk Law students, a Our e-filing tools are a little harder to see in action, but we'd be happen to do a demo if you [email us](mailto:litlab@suffolk.edu). -Docassemble and the Document Assembly Line tools are open source, so courts and orgs can use them with confidence that the underlying software will be free to use, forever, with no vendor lock-in. Instead, we are building digital public infrastructure together. +docassemble and the Document Assembly Line tools are open source, so courts and orgs can use them with confidence that the underlying software will be free to use, forever, with no vendor lock-in. Instead, we are building digital public infrastructure together. -If you want to try building an interview with Docassemble and the Document Assembly Line tools, follow our [beginner's guide](beginners_guide.md). +If you want to try building an interview with docassemble and the Document Assembly Line tools, follow our [beginner's guide](beginners_guide.md). ## Join the community {#join-the-community} -The Document Assembly Line community is free to join and open to courts, legal aid organizations, and anyone else interested in building online guided interviews with Docassemble and the Document Assembly Line Tools. +The Document Assembly Line community is free to join and open to courts, legal aid organizations, and anyone else interested in building online guided interviews with docassemble and the Document Assembly Line Tools. We offer: @@ -57,7 +57,7 @@ To join the community, just [email us](mailto:litlab@suffolk.edu)! ## Get involved/support our work -- We offer affordable Docassemble hosting and e-filing tools for courts and legal aid organizations. Interested? [Email us!](mailto:litlab@suffolk.edu) +- We offer affordable docassemble hosting and e-filing tools for courts and legal aid organizations. Interested? [Email us!](mailto:litlab@suffolk.edu) - We need [volunteers](/docs/volunteer/volunteer.mdx) to help update, test, and translate interviews. We also need volunteers to help us organize volunteers. - We also accept [donations](https://www.givecampus.com/campaigns/70271/donations/new) to help us continue developing these free and open-source tools. @@ -65,23 +65,23 @@ To join the community, just [email us](mailto:litlab@suffolk.edu)! All code generated as part of this project is available for free [on GitHub](https://github.com/SuffolkLITLab) under the [MIT license](https://opensource.org/license/mit). -### Docassemble interview-building tools +### docassemble interview-building tools * [The core AssemblyLine package](https://github.com/SuffolkLITLab/docassemble-AssemblyLine) contains runtime code and shared questions for interviews. * [ALWeaver](https://github.com/SuffolkLITLab/docassemble-ALWeaver) is a tool for rapidly generating interviews from marked-up court form PDF and DOCX templates. -* [ALToolbox](https://github.com/SuffolkLITLab/docassemble-ALToolbox) contains functions and components that might benefit Docassemble developers whether or not they choose not to install the full Document Assembly Line toolbox. -* [ALRecipes](https://github.com/SuffolkLITLab/docassemble-ALRecipes) examples and snippets that use Assembly Line features or demonstrate best practices. Can be included directly in the Docassemble Playground to supplement the list of Playground examples. -* [PovertyScale](https://github.com/SuffolkLITLab/docassemble-PovertyScale) which contains a Python library, Docassemble code, static JSON and a REST server for determining income qualification based on the [United States Federal Poverty Scale](https://web.archive.org/web/20250528044709/http://aspe.hhs.gov/topics/poverty-economic-mobility/poverty-guidelines), updated on an annual basis. -* [GithubFeedbackForm](https://github.com/SuffolkLITLab/docassemble-GithubFeedbackForm) helps Docassemble authors collect feedback from users and generate GitHub issues. +* [ALToolbox](https://github.com/SuffolkLITLab/docassemble-ALToolbox) contains functions and components that might benefit docassemble developers whether or not they choose not to install the full Document Assembly Line toolbox. +* [ALRecipes](https://github.com/SuffolkLITLab/docassemble-ALRecipes) examples and snippets that use Assembly Line features or demonstrate best practices. Can be included directly in the docassemble Playground to supplement the list of Playground examples. +* [PovertyScale](https://github.com/SuffolkLITLab/docassemble-PovertyScale) which contains a Python library, docassemble code, static JSON and a REST server for determining income qualification based on the [United States Federal Poverty Scale](https://web.archive.org/web/20250528044709/http://aspe.hhs.gov/topics/poverty-economic-mobility/poverty-guidelines), updated on an annual basis. +* [GithubFeedbackForm](https://github.com/SuffolkLITLab/docassemble-GithubFeedbackForm) helps docassemble authors collect feedback from users and generate GitHub issues. -### Docassemble server tools +### docassemble server tools -* [ALDashboard](https://github.com/SuffolkLITLab/docassemble-ALDashboard) is a Document Assembly Line–independent tool that makes it easier to maintain a Docassemble server. +* [ALDashboard](https://github.com/SuffolkLITLab/docassemble-ALDashboard) is a Document Assembly Line–independent tool that makes it easier to maintain a docassemble server. * [InterviewStats](https://github.com/SuffolkLITLab/docassemble-InterviewStats/) for gathering usage analytics. ### E-filing -* [EFSP Integration](https://github.com/SuffolkLITLab/docassemble-EFSPIntegration/) is a Python and Docassemble frontend for Suffolk Law School's electronic filing Java server. +* [EFSP Integration](https://github.com/SuffolkLITLab/docassemble-EFSPIntegration/) is a Python and docassemble frontend for Suffolk Law School's electronic filing Java server. * [EFileProxyServer](https://github.com/SuffolkLITLab/EfileProxyServer) is a Java-based REST server that provides a simplified interface to [Tyler EFMs](https://www.tylertech.com/products/odyssey/file-serve), as well as an interface to JeffNet, the home-brew efiling server run by Jefferson Parish, Louisiana. * [LITEfile](https://github.com/SuffolkLITLab/LITEFile) is a standalone e-filing tool built for self-represented litigants \ No newline at end of file diff --git a/docs/get_started/plan_interview.md b/docs/get_started/plan_interview.md index 85cc88a94..dd54333af 100644 --- a/docs/get_started/plan_interview.md +++ b/docs/get_started/plan_interview.md @@ -13,7 +13,7 @@ To automate a form using the Assembly Line framework, you must: 1. identify the template that you will use: either a PDF or DOCX template 1. add digital **field labels** where the information the user provides will go 1. run the labeled template through the Assembly Line Weaver -1. download the "weaved" form and refine in your Docassemble playground +1. download the "weaved" form and refine in your docassemble playground 1. test, respond to feedback, and iterate 1. deploy to a production server and add links on your public website diff --git a/docs/get_started/resources.mdx b/docs/get_started/resources.mdx index d82c4347e..a2046d4d2 100644 --- a/docs/get_started/resources.mdx +++ b/docs/get_started/resources.mdx @@ -23,9 +23,9 @@ If you've already joined us in Teams: ## Interview building resources :::info -In order to build Docassemble interviews you will need access to a Docassemble development server. The LIT Lab has a shared dev server for our students, our [court and legal aid partners](/#partners) (current and prospective), and [Document Assembly Line volunteers](/docs/volunteer/sign_up). If you are a partner or volunteer, use [this workflow](/docs/volunteer/flows#dev-server) to get access to the LIT Lab dev server. +In order to build docassemble interviews you will need access to a docassemble development server. The LIT Lab has a shared dev server for our students, our [court and legal aid partners](/#partners) (current and prospective), and [Document Assembly Line volunteers](/docs/volunteer/sign_up). If you are a partner or volunteer, use [this workflow](/docs/volunteer/flows#dev-server) to get access to the LIT Lab dev server. -Otherwise, you'll need to [set up your own Docassemble server](https://docassemble.org/docs/installation.html). It looks intimidating, but it's not too hard! If you run into problems, you can ask for help in the [**Server admin** channel](https://teams.microsoft.com/l/channel/19%3Ad8d78c13648140308a2cc1670a4fdd06%40thread.tacv2/Server%20admin?groupId=eaa9bd9d-cf39-4686-8f30-e55aa9d98c75&tenantId=78733fa9-540e-4eb8-bf29-73c4eeb63412) in Teams. +Otherwise, you'll need to [set up your own docassemble server](https://docassemble.org/docs/installation.html). It looks intimidating, but it's not too hard! If you run into problems, you can ask for help in the [**Server admin** channel](https://teams.microsoft.com/l/channel/19%3Ad8d78c13648140308a2cc1670a4fdd06%40thread.tacv2/Server%20admin?groupId=eaa9bd9d-cf39-4686-8f30-e55aa9d98c75&tenantId=78733fa9-540e-4eb8-bf29-73c4eeb63412) in Teams. ::: ### Training @@ -54,7 +54,7 @@ Individual training sessions: - [Experimental PDF editor](https://nonprofittechy.github.io/pdf-editor-ui/) - [ALWeaver](https://apps-dev.suffolklitlab.org/run/generator) -#### ALKiln (testing suite for Docassemble interviews) +#### ALKiln (testing suite for docassemble interviews) - [Intro](../components/ALKiln/intro.mdx) - [Setup](../components/ALKiln/setup.mdx) @@ -66,7 +66,7 @@ If you are stuck on something for longer than 20 minutes, it's probably time to - Seek help in the [**Coding help** channel](https://teams.microsoft.com/l/channel/19%3Ae16e9e9701a5445ea4035b5cb776a4cc%40thread.tacv2/Coding%20help?groupId=eaa9bd9d-cf39-4686-8f30-e55aa9d98c75&tenantId=78733fa9-540e-4eb8-bf29-73c4eeb63412) in Teams - Come to our [weekly community standups](https://suffolk.zoom.us/j/95053079942), Michelle's office hours, or our other [community meetings](https://sumail.sharepoint.com/:b:/r/sites/LegalInnovationandTechnologyLab/Shared%20Documents/General/DAL%20community%20meetings.pdf?csf=1&web=1&e=a3eLL9) -- Ask in the [Docassemble Slack group](https://join.slack.com/t/docassemble/shared_invite/zt-2cspzjo9j-YyE7SrLmi5muAvnPv~Bz~A) +- Ask in the [docassemble Slack group](https://join.slack.com/t/docassemble/shared_invite/zt-2cspzjo9j-YyE7SrLmi5muAvnPv~Bz~A) :::tip For best results when asking for help: @@ -93,9 +93,9 @@ While building interviews you will most likely have one or more documentation we These are the essential documentation websites to have on hand: - [This website](/) -- [Docassemble docs](https://docassemble.org/docs.html) +- [docassemble docs](https://docassemble.org/docs.html) -Docassemble interview files use several kinds of markup. Most of what you will need to know is included on the [Docassemble markup page](https://docassemble.org/docs/markup.html), but sometimes you may need to go to the source for more detailed documentation. +docassemble interview files use several kinds of markup. Most of what you will need to know is included on the [docassemble markup page](https://docassemble.org/docs/markup.html), but sometimes you may need to go to the source for more detailed documentation. - [YAML](https://yaml.org/spec/1.2/spec.html) (the base file format) - [Markdown](https://daringfireball.net/projects/markdown/) (formatting text) @@ -103,14 +103,14 @@ Docassemble interview files use several kinds of markup. Most of what you will n - [Python](https://docs.python.org/3/reference/index.html) (coding in Mako tags and [code blocks](https://docassemble.org/docs/code.html)) - [Jinja](https://jinja.palletsprojects.com/en/3.0.x/) (used in [DOCX templates](../authoring/docx_templates.md)) -You can also use [HTML](https://docassemble.org/docs/markup.html#markdownhtml), [CSS](https://docassemble.org/docs/ui.html#css), and [Javascript](https://docassemble.org/docs/initial.html#javascript) in Docassemble interviews. +You can also use [HTML](https://docassemble.org/docs/markup.html#markdownhtml), [CSS](https://docassemble.org/docs/ui.html#css), and [Javascript](https://docassemble.org/docs/initial.html#javascript) in docassemble interviews. - [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML) (advanced formatting) - [CSS](https://developer.mozilla.org/en/docs/Web/CSS/Reference) (customizing the UI) - [Javascript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) and [jQuery](https://api.jquery.com/) (advanced customization) :::info JavaScript Workshop Resource -📺 **First Wednesday Workshop:** For practical guidance on integrating JavaScript into your Docassemble interviews, watch our workshop [Using JavaScript in Docassemble](https://suffolklitlab.org/using-javascript-in-docassemble/). This session covers common JavaScript patterns, jQuery integration, and best practices for enhancing interview functionality. +📺 **First Wednesday Workshop:** For practical guidance on integrating JavaScript into your docassemble interviews, watch our workshop [Using JavaScript in docassemble](https://suffolklitlab.org/using-javascript-in-docassemble/). This session covers common JavaScript patterns, jQuery integration, and best practices for enhancing interview functionality. ::: ## Volunteer resources diff --git a/docs/overview.md b/docs/overview.md index e0e6babca..53d4137c1 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,12 +1,12 @@ --- id: overview -title: Developing with Docassemble and the Document Assembly Line +title: Developing with docassemble and the Document Assembly Line sidebar_label: Overview slug: overview --- ## This documentation covers the custom stuff -Please review [Introduction to Docassemble](docassemble_intro/introduction-to-docassemble.md) (and the pages that follow) for a readable, step-by-step guide to the core features and syntax of Docassemble, such as: +Please review [Introduction to docassemble](docassemble_intro/introduction-to-docassemble.md) (and the pages that follow) for a readable, step-by-step guide to the core features and syntax of docassemble, such as: -See [The official Docassemble documentation](https://docassemble.org/docs.html) for everything else. Be aware that the official documentation has a **lot** of content. Feel free to ask for help finding the right link! +See [The official docassemble documentation](https://docassemble.org/docs.html) for everything else. Be aware that the official documentation has a **lot** of content. Feel free to ask for help finding the right link! diff --git a/docs/style_guide/question_library/addresses.md b/docs/style_guide/question_library/addresses.md index bcd2ad983..e8e683273 100644 --- a/docs/style_guide/question_library/addresses.md +++ b/docs/style_guide/question_library/addresses.md @@ -44,7 +44,7 @@ fields: ``` - + ```yaml --- @@ -95,7 +95,7 @@ fields: ``` - + ```yaml --- @@ -160,7 +160,7 @@ fields: ``` - + ```yaml --- @@ -262,7 +262,7 @@ fields: ``` - + ```yaml --- @@ -395,7 +395,7 @@ fields: ``` - + ```yaml --- @@ -451,7 +451,7 @@ fields: ``` - + ```yaml id: contact information diff --git a/docs/style_guide/question_library/gender.md b/docs/style_guide/question_library/gender.md index 5484cf467..e609ebdfa 100644 --- a/docs/style_guide/question_library/gender.md +++ b/docs/style_guide/question_library/gender.md @@ -59,7 +59,7 @@ For example: could replace it. * we add a space for the user's self-described gender in other circumstances -### Adding gender fields in Docassemble +### Adding gender fields in docassemble @@ -75,7 +75,7 @@ fields: ``` - + ```yaml --- diff --git a/docs/style_guide/question_library/language.md b/docs/style_guide/question_library/language.md index 97e4700e7..d4e34345d 100644 --- a/docs/style_guide/question_library/language.md +++ b/docs/style_guide/question_library/language.md @@ -59,7 +59,7 @@ language that they will answer questions in the guided interview with. When allowing the user to change the guided interview's language, use the native language name. -### Adding language fields in Docassemble +### Adding language fields in docassemble @@ -75,7 +75,7 @@ fields: ``` - + ```yaml sets: diff --git a/docs/style_guide/question_library/names.md b/docs/style_guide/question_library/names.md index b3026b44a..39fa77c4b 100644 --- a/docs/style_guide/question_library/names.md +++ b/docs/style_guide/question_library/names.md @@ -50,7 +50,7 @@ fields: ``` - + ```yaml --- @@ -97,7 +97,7 @@ fields: ``` - + ```yaml --- @@ -138,7 +138,7 @@ fields: ``` - + ```yaml --- diff --git a/docs/style_guide/question_library/pronouns.md b/docs/style_guide/question_library/pronouns.md index 740d1c018..348c3e0b8 100644 --- a/docs/style_guide/question_library/pronouns.md +++ b/docs/style_guide/question_library/pronouns.md @@ -71,7 +71,7 @@ The Assembly Line team also chose to add these additional options: We experimented with randomizing the order of pronouns. Ultimately, we decided to keep a familiar order. -### Adding pronoun fields in Docassemble +### Adding pronoun fields in docassemble @@ -87,7 +87,7 @@ fields: ``` - + ```yaml --- diff --git a/docs/style_guide/question_style_navigation.md b/docs/style_guide/question_style_navigation.md index 9ee4fc584..77d598167 100644 --- a/docs/style_guide/question_style_navigation.md +++ b/docs/style_guide/question_style_navigation.md @@ -26,14 +26,14 @@ to request the court to waive fees: 1. Download and next steps In a HotDocs interview, these sections will correspond 1 to 1 to pages and -titles of pages in the interview. In Docassemble, you must add these sections +titles of pages in the interview. In docassemble, you must add these sections separately. -In a Docassemble interview, consider using the sections to allow the user to +In a docassemble interview, consider using the sections to allow the user to edit and review their answers as they use the interview. This requires additional work but may build the user's confidence as they use your website. -Example of Docassemble's standard navigation: +Example of docassemble's standard navigation: ![](./assets/example_navigation_guardianship.png) diff --git a/docs/style_guide/question_style_organize_fields.md b/docs/style_guide/question_style_organize_fields.md index c9908eb6f..df2e0550c 100644 --- a/docs/style_guide/question_style_organize_fields.md +++ b/docs/style_guide/question_style_organize_fields.md @@ -74,7 +74,7 @@ to place one question on each screen. Others, like HotDocs, can be formatted like a busy paper form, with dozens of fields on a screen in multiple columns. -Docassemble is mobile first, and in mobile design of surveys, studies show that the best design +docassemble is mobile first, and in mobile design of surveys, studies show that the best design to reduce interview time for the user and to reduce fatigue emphasizes "scrolling" (multiple fields per screen) over "paging" (one question per screen). diff --git a/docs/style_guide/style_guide_formatting.md b/docs/style_guide/style_guide_formatting.md index caf0ab7ff..341dee9c0 100644 --- a/docs/style_guide/style_guide_formatting.md +++ b/docs/style_guide/style_guide_formatting.md @@ -53,7 +53,7 @@ Writing a long, descriptive prompt that includes obvious directions is a common mistake made by new developers. Short labels are usually easier and faster to process than long questions. -Most prompts (the text that is to the left of the field in a normal Docassemble interview) +Most prompts (the text that is to the left of the field in a normal docassemble interview) should stay on one line. #### Omit obvious instruction verbs like "write" or "enter" @@ -62,7 +62,7 @@ Verbs like "enter", "write", or "list" are unnecessary in a field label. #### Consider labeling optional fields {#label-optional} -Docassemble adds a red asterisk (`*`) next to required fields, but when most +docassemble adds a red asterisk (`*`) next to required fields, but when most fields on the screen are required, it may be helpful to label optional fields instead. This is especially useful when the user is presented an area field to enter a potentially long explanation. diff --git a/docs/style_guide/style_guide_readability.md b/docs/style_guide/style_guide_readability.md index 06da578bc..a6c14fa46 100644 --- a/docs/style_guide/style_guide_readability.md +++ b/docs/style_guide/style_guide_readability.md @@ -22,7 +22,7 @@ with significant numbers of Americans reading at a lower level. You can measure the readability of your text with automated tools: -* in Docassemble, by [clicking the "source" button](https://docassemble.org/docs/helloworld.html#tocAnchor-1-1) +* in docassemble, by [clicking the "source" button](https://docassemble.org/docs/helloworld.html#tocAnchor-1-1) * by installing the free [WriteClearly bookmarklet](https://www.openadvocate.org/writeclearly/) * by using free tools such as [Hemingway](https://hemingwayapp.com/) diff --git a/docs/volunteer/flows.mdx b/docs/volunteer/flows.mdx index a05f638b5..a28ea8d59 100644 --- a/docs/volunteer/flows.mdx +++ b/docs/volunteer/flows.mdx @@ -45,7 +45,7 @@ This page contains step-by-step workflows for volunteers. Not a volunteer? Join After you complete the [interview builder training](../get_started/resources#training) and final project, you are ready for your first issue! (An *issue* is an update, bug, enhancement, or other coding task.) - When you are first starting to work on Docassemble interviews, it can be hard to judge the level of difficulty of an issue. We identify good issues for new builders with the **starter** label in GitHub. Sometimes we misjudge, so if you end up with an issue that seems above your skill level, [check in with us](../get_started/resources#communication). + When you are first starting to work on docassemble interviews, it can be hard to judge the level of difficulty of an issue. We identify good issues for new builders with the **starter** label in GitHub. Sometimes we misjudge, so if you end up with an issue that seems above your skill level, [check in with us](../get_started/resources#communication). To get started on your first issue: @@ -94,12 +94,12 @@ import TabItem from '@theme/TabItem'; TBD - 1. [Register for a LIT Lab Docassemble server account](https://apps-dev.suffolklitlab.org/user/register) on the development server. You will then be a regular user. Use your registration email address to [email us](mailto:litlab@suffolk.edu "mailto:litlab@suffolk.edu") a request for a developer account. Remember to include some context about yourself. + 1. [Register for a LIT Lab docassemble server account](https://apps-dev.suffolklitlab.org/user/register) on the development server. You will then be a regular user. Use your registration email address to [email us](mailto:litlab@suffolk.edu "mailto:litlab@suffolk.edu") a request for a developer account. Remember to include some context about yourself. 1. If you have a GitHub account, log into your GitHub account. If you lack a GitHub account, make one: 1. Choose a GitHub username. If you want more privacy, choose a name that is unrelated to you and unrelated to anyone and anything in your life. 1. [Make the GitHub account](https://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F&source=header-home). 1. If you want to increase privacy, set [your GitHub account's email settings](https://github.com/settings/emails) to keep your email private and choose to block pushes that expose your email. - 1. Go to [your GitHub integration page on the LIT Lab Docassemble server](https://apps-dev.suffolklitlab.org/github_menu) and authorize your GitHub account. + 1. Go to [your GitHub integration page on the LIT Lab docassemble server](https://apps-dev.suffolklitlab.org/github_menu) and authorize your GitHub account. TBD diff --git a/docs/volunteer/volunteer.mdx b/docs/volunteer/volunteer.mdx index ef69ea1c7..c416452ab 100644 --- a/docs/volunteer/volunteer.mdx +++ b/docs/volunteer/volunteer.mdx @@ -38,7 +38,7 @@ There are many other situations where guided interviews can make a difference by The free guided interviews on Court Forms Online are built by students, courts, legal aid organizations, and volunteers across the US. But building, expanding, and maintaining such a large collection of forms is a lot of work! Some have bugs or need updates due to changes in the law, procedures, or official court forms. Some need to be translated. Most could be improved. -Our goal is to train and organize volunteers to help us do that work. In exchange, we'll teach you to work with cutting-edge legal technology like Docassemble and artificial intelligence. Sound like something you'd like to be a part of? +Our goal is to train and organize volunteers to help us do that work. In exchange, we'll teach you to work with cutting-edge legal technology like docassemble and artificial intelligence. Sound like something you'd like to be a part of? @@ -79,11 +79,11 @@ You can work on one interview or many, depending on the time you can contribute ### Builders -Build and update online guided interviews! This involves coding in Docassemble, but **no coding experience is necessary to join this team**. We will teach you everything you need to get started and support you with regular check-ins. You just need to be willing to learn! +Build and update online guided interviews! This involves coding in docassemble, but **no coding experience is necessary to join this team**. We will teach you everything you need to get started and support you with regular check-ins. You just need to be willing to learn! Building interviews is an ongoing project, and the updates team requires a long-term commitment. Volunteers should be able to commit at least 5–10 hours per month for at least 3 months. -In addition to the tools above, builders will need to work with Docassemble and GitHub (but we'll teach you what you need to know). +In addition to the tools above, builders will need to work with docassemble and GitHub (but we'll teach you what you need to know). ### Translators diff --git a/docusaurus.config.js b/docusaurus.config.js index 79152df8e..b35da10c7 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -47,7 +47,7 @@ module.exports = { }, { href: 'https://docassemble.org/docs.html', - label: 'Docassemble docs', + label: 'docassemble docs', position: 'right', }, { diff --git a/make_interview_docs.py b/make_interview_docs.py index 189a4f226..3364331f2 100755 --- a/make_interview_docs.py +++ b/make_interview_docs.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 """ -Run this to generate documentation pages from Docassemble interview files directly, +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 diff --git a/sidebars.js b/sidebars.js index 540f5a645..8ebeb3cae 100644 --- a/sidebars.js +++ b/sidebars.js @@ -54,7 +54,7 @@ module.exports = { docs: [ 'overview', { - label: 'Introduction to Docassemble', + label: 'Introduction to docassemble', type: 'category', items: [ 'docassemble_intro/introduction-to-docassemble', @@ -66,7 +66,7 @@ module.exports = { 'docassemble_intro/basic-troubleshooting', { type: "category", - label: "Docassemble syntax", + label: "docassemble syntax", items: [ 'docassemble_intro/yaml', 'docassemble_intro/markdown', @@ -85,7 +85,7 @@ module.exports = { }, { type: 'category', - label: 'Administering Docassemble', + label: 'Administering docassemble', items: [ 'admin_guide_docassemble/setup-server', 'admin_guide_docassemble/rebuild-lightsail-instance', diff --git a/src/pages/index.tsx b/src/pages/index.tsx index 68bc15038..a5953c89d 100644 --- a/src/pages/index.tsx +++ b/src/pages/index.tsx @@ -98,7 +98,7 @@ function Home() {

- Build beautiful, responsive, accessible online guided interviews with Docassemble and the Document Assembly Line tools. + Build beautiful, responsive, accessible online guided interviews with docassemble and the Document Assembly Line tools.

  • Accessible and responsive by design
    • @@ -139,7 +139,7 @@ function Home() {

- Suffolk's open-source e-filing service provider (EFSP) delivers completed forms to court e-filing systems directly from Docassemble interviews. + Suffolk's open-source e-filing service provider (EFSP) delivers completed forms to court e-filing systems directly from docassemble interviews.

  • Removes a major obstacle for self-represented litigants (SRLs)
    • @@ -217,9 +217,9 @@ function Home() { __html: translate({ id: 'homepage.benefits.dalIsFOSS', description: - 'All Document Assembly Line and Docassemble code is free and open source, released under the MIT license.', + 'All Document Assembly Line and docassemble code is free and open source, released under the MIT license.', message: - 'All Document Assembly Line and Docassemble code is free and open source, released under the MIT license.', + 'All Document Assembly Line and docassemble code is free and open source, released under the MIT license.', }), }}>

      @@ -291,7 +291,7 @@ function Home() {

- To facilitate the adoption of open-source access-to-justice tools, we offer affordable Docassemble hosting and e-filing tools for courts and legal aid organizations. If you are interested, send us an email. + To facilitate the adoption of open-source access-to-justice tools, we offer affordable docassemble hosting and e-filing tools for courts and legal aid organizations. If you are interested, send us an email.