Municipal Election support updates

README.md

@@ -1,139 +1,166 @@
+# Tally-Ho
+
 ![Build Status](https://github.com/onaio/tally-ho/actions/workflows/config.yml/badge.svg?branch=master)
 [![codecov](https://codecov.io/github/onaio/tally-ho/branch/master/graph/badge.svg?token=1PR3KIqgr6)](https://codecov.io/github/onaio/tally-ho)
 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/1e817ebba18946fa84cb129cdc914f0b)](https://app.codacy.com/gh/onaio/tally-ho/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
 
-## Tally-Ho!
+## Overview
 
-Election results data entry and verification software built by [Ona Systems](http://company.ona.io) and commissioned by the Libyan [High National Elections Commission](http://hnec.ly/) and the [United Nations Development Program](http://www.undp.org).
+Election results data entry and verification software built by [Ona Systems](http://company.ona.io), commissioned by the Libyan [High National Elections Commission](http://hnec.ly/) and [UNDP](http://www.undp.org).
 
-## Quick install
+## Quick Install
 
-### Checkout the repos
+### Checkout the Repository
 
 ```bash
 git clone git@github.com:onaio/tally-ho.git
 ```
 
-### Make a virtual environment and install requirements
+### Set Up Virtual Environment and Install Requirements
 
-Prerequisites: this assumes you have [virtualenvwrapper](http://virtualenvwrapper.readthedocs.org/en/latest/install.html) and [PostgreSQL](https://wiki.postgresql.org/wiki/Detailed_installation_guides) installed.
+Prerequisites: Ensure [virtualenvwrapper](http://virtualenvwrapper.readthedocs.org/en/latest/install.html) and [PostgreSQL](https://wiki.postgresql.org/wiki/Detailed_installation_guides) are installed.
 
 ```bash
 mkvirtualenv tally --python=python3.9
 pip install -r requirements/dev.pip
 ```
 
-Install `libpq-dev` library that contains a minimal set of `PostgreSQL`_ binaries and headers requried
-for building 3rd-party applications for `PostgreSQL`_.
+Install `libpq-dev` for PostgreSQL headers:
+
 ```bash
 sudo apt-get install libpq-dev
 ```
 
-Install memcache
-```bash
-sudo apt-get update && sudo apt-get install -y memcached
-```
+Install memcached and Redis:
 
-Install redis
 ```bash
-sudo apt-get install -y redis-server
+sudo apt-get update && sudo apt-get install -y memcached redis-server
 ```
 
-Make sure you have the latest versions of pip, wheel, and setuptools installed, run
+Ensure latest versions of pip, wheel, and setuptools:
+
 ```bash
 python -m pip install -U pip wheel setuptools
 ```
 
-To Enable [pre-commit hook checks](https://pre-commit.com/#3-install-the-git-hook-scripts) for development, in your virtual env, run
+Enable [pre-commit hook checks](https://pre-commit.com/#3-install-the-git-hook-scripts):
+
 ```bash
 pre-commit install
 ```
 
-### Running celery
+### Running Celery
 
 ```bash
 celery -A tally_ho.celeryapp worker --loglevel=info
 ```
-### Quick start with user demo data
 
-> This will remove all data in the database.
+### Quick Start with User Demo Data
 
-To create the database, load demo users, and start the server all in one, run
+> **Warning**: This will erase all database data.
 
 ```bash
 ./scripts/quick_start
 ```
 
-If you've aleady setup the server, you can start the server with
+If server setup is complete, start the server:
 
 ```bash
 python manage.py runserver --settings=tally_ho.settings.dev
 ```
 
-### Loading tally demo data
-
-> TODO: add some demo result forms and candidate lists
+### Loading Tally Demo Data
 
-### Advanced: recreate the database, then load the data and demo users
+> **Note**: Add demo result forms and candidate lists.
 
-> This will remove all data in the database.
+### Advanced: Recreate Database and Load Demo Users
 
-> This will only work if you have data files in the folder `./data`
-
-The first argument is the database user, the second is the database host IP
-address, and the third is the settings file. Modify these arguments as needed.
+> **Warning**: This erases all database data and only works with files in `./data`.
 
 ```bash
 ./scripts/reload_all postgres 127.0.0.1 tally_ho.settings.common
 ```
 
-## Docker Install
+## Docker Installation
 
-If you already have Docker and `docker-compose` installed on your machine you can quickly have a demo up by changing into the checked out code directory and running:
+With Docker and `docker-compose` installed, build and run:
 
 ```bash
 docker-compose build
 docker-compose up
 ```
 
-You can now visit the site at `127.0.0.1:8000`.
-
-If you want to use Docker to run the site in production you will need to:
+Visit `127.0.0.1:8000`. For production, modify the `docker-compose.yml` file:
 
-1. modify the `docker-compose.yml` file to change the NGINX listening port from 8000 to 80,
-2. add the host you are running the site on to a new `ALLOWED_HOSTS` list in the `tally_ho/settings/docker.py` file.
+1. Change NGINX port from 8000 to 80.
+2. Add your host to `ALLOWED_HOSTS` in `tally_ho/settings/docker.py`.
 
 ## Running Tests
 
-run `pytest tally_ho`
+Run tests with:
+
+```bash
+pytest tally_ho
+```
 
 ## Documentation
 
+### Arabic Translations
+
+Follow these steps for managing Arabic translations:
+
+1. **Add Arabic Language**: Update `settings.py`:
+
+    ```python
+    # settings.py
+        LANGUAGES = [
+            ('en', 'English'),
+            ('ar', 'Arabic'),
+    ]
+
+    # Ensure LANGUAGE_CODE is set to a default language (e.g., 'en')
+        LANGUAGE_CODE = 'en'
+    ```
+
+2. **Generate Arabic Translation Files**:
+
+    ```bash
+    django-admin makemessages -l ar
+    ```
+
+3. **Edit Arabic Translations**: Update `locale/ar/LC_MESSAGES/django.po`.
+
+4. **Compile Translations**:
+
+    ```bash
+    django-admin compilemessages
+    ```
+
 ### Generating Model Graphs
 
-The below assumes you have `pip` installed `requirements/dev.pip` and [graphviz](https://graphviz.org/download/) in your machine.
+Install requirements from `requirements/dev.pip` and [graphviz](https://graphviz.org/download/).
 
-Generate model graph for all models:
+Generate all model graphs:
 
-```
+```bash
 python manage.py graph_models --settings=tally_ho.settings.dev --pydot -a -g -o tally-ho-all-models.png
 ```
 
-Generate model graph for app models:
+Generate specific app model graphs:
 
-```
-python manage.py graph_models --settings=tally_ho.settings.dev --pydot -a -X GroupObjectPermission,UserObjectPermission,GroupObjectPermissionBase,BaseGenericObjectPermission,UserObjectPermissionBase,BaseObjectPermission,Version,Revision,Pageview,Visitor,Session,AbstractBaseSession,Site,LogEntry,User,Group,AbstractUser,Permission,ContentType,AbstractBaseUser,PermissionsMixin,BaseModel -g -o tally-ho-app-models.png
+```bash
+python manage.py graph_models --settings=tally_ho.settings.dev --pydot -a -X GroupObjectPermission,... -g -o tally-ho-app-models.png
 ```
 
 ### Demo Users
 
-The `create_demo_users` command will create demo users for each role with usernames like `super_administrator`, and password `data`.
+Use the `create_demo_users` command to create demo users with usernames like `super_administrator`, and password `data`.
 
 ### File Uploads
 
-The `MAX_FILE_UPLOAD_SIZE` variable in `tally_ho/settings/common.py` file defines the file upload limit which is currently set to 10MB.
+File upload limit is set to 10MB in `MAX_FILE_UPLOAD_SIZE` within `tally_ho/settings/common.py`.
 
 ## News
 
-- This is an [article about tally-ho](https://ona.io/home/writing-python-code-to-decide-an-election-2/) and its use in Libya.
-- This presentation at PyConZA 2014 about the project, [Writing Python Code to Decide an Election](https://ona.io/home/writing-python-code-to-decide-an-election-2/).
+- Article: [Writing Python Code to Decide an Election](https://ona.io/home/writing-python-code-to-decide-an-election-2/).
+- PyConZA 2014 presentation: [Writing Python Code to Decide an Election](https://ona.io/home/writing-python-code-to-decide-an-election-2/).

docs/overview/README.md

@@ -1,4 +1,4 @@
-## System Overview
+# System Overview
 
 **tally-system** is used to record, verify, and report the results of paper votes
 that have been used in an election.  Tally centers enter *result forms* and
@@ -83,7 +83,7 @@ form is not a replacement form it will have a pre-assigned center and station.
 If it is a replacement form the clerk will next enter the center and station
 number for that form.
 
-![](images/intake.png)
+![Intake](images/intake.png)
 
 The original form or the replacement form is a duplicate if there is already a
 form in the system with the same ballot, center, and station.  If the form is a
@@ -115,17 +115,17 @@ The Data Entry Clerk begins by entering the barcode for a form they have
 received.  The system then shows the results component, which displays the
 candidates that appear on the ballot assigned
 to the form in the order in which they appear on the ballot (and form).  The physical form
-shows the number of results for each candidate.  The Data Entry Clerk must enter the 
+shows the number of results for each candidate.  The Data Entry Clerk must enter the
 results for each candidate that appear on the form into the system.
 
-![](images/data-entry-results.png)
+![Data entry results](images/data-entry-results.png)
 
 If the form contains a reconcilliation component, the Clerk must also enter
 reconciliation information regarding the number of ballots, number of stampted
 votes, number of damaged votes, etc.  The system will use this information
 later when deciding whether to Audit the form.
 
-![](images/data-entry.png)
+![data entry](images/data-entry.png)
 
 After a Data Entry 1 Clerk has entered the form's information, the system moves the
 form to Data Entry 2 and the Clerk is instructed to move the physical form to
@@ -141,9 +141,9 @@ and 2 matches exactly the Clerk is simply displayed a message and the form is
 moved to quality control.  The Corrections Clerk begins by entering a barcode
 for the form they have received.
 
-![](images/corrections.png)
+![corrections](images/corrections.png)
 
-If any entries do not match, the system displays the information entered 
+If any entries do not match, the system displays the information entered
 during Data Entry 1 and 2 side-by-side.  The Corrections Clerk must select the
 correct information and select "Submit Corrections", "Not Correct - Reject", or
 "Abort".  If the Clerk chooses "Submit" the corrections are stored and the form
@@ -154,7 +154,7 @@ in the pipeline from there.  If the Clerk choose "Abort" no corrections are
 saved, the forms stays in corrections, and the Clerk is returned to the enter
 barcode entry screen.
 
-![](images/corrections-results.png)
+![corrections results](images/corrections-results.png)
 
 ### Quality Control
 
@@ -169,7 +169,7 @@ form is move to Data Entry 1 and continues in the pipeline from there.  If the
 Clerk chooses "Abort" the form stays in quality control, and the Clerk is
 returned to the enter barcode screen.
 
-![](images/quality-control.png)
+![quality control](images/quality-control.png)
 
 ### Archiving
 
@@ -187,7 +187,7 @@ Otherwise, the Archiving Clerk prints an *Archived* cover sheet and attaches it
 to the form.  The Clerk selects "Print Successful", moving the form to archived
 state.  The form is then filed away.
 
-![](images/archive.png)
+![archive](images/archive.png)
 
 ## Review Stages
 
@@ -223,7 +223,7 @@ recommendations made by a clerk for the form the choose
 the system moves form to Unsubmitted state, and the physical form is returned to
 the Intake Section.
 
-![](images/clearance.png)
+![clearance](images/clearance.png)
 
 ### Audit
 
@@ -260,7 +260,7 @@ recommending that the form skip Quarantine Checks on its next time through the
 system.  The form is then hidden from the Audit team and must then be reviewed
 by a Super Administration before moving to Data Entry 1.
 
-![](images/audit-review.png)
+![audit review](images/audit-review.png)
 
 ## Super Administrator Views
 
@@ -277,7 +277,7 @@ change.  The *Forms Waiting For Approval* list shows those forms which a Super
 Administrator must review.  Rows in this list link to the Audit review view for
 the forms.
 
-![](images/admin-review.png)
+![admin review](images/admin-review.png)
 
 ### Reports Views
 
@@ -286,15 +286,15 @@ current state within the system.  This view is useful to determine where a form
 is in processing and to see how many forms from a particular center have been
 entered into the system.
 
-![](images/reports-progress.png)
+![reports progress](images/reports-progress.png)
 
 The *Reports Offices* list shows the percentage of forms in each state within
 the system.  This can be used to balance the Clerk assigned to specific
 stations.  For example, if there are twice as many forms in Data Entry 1 than
 in Data Entry 2, it may be wise to assign some Clerk from Data Entry 2 to Dat
 Entry 1.
 
-![](images/reports-race.png)
+![reports race](images/reports-race.png)
 
 This view also shows the number of Intaken and Archived form for each Office
 (analogous to a type of voting district).  This allows administrators to track
@@ -319,12 +319,11 @@ that can be entered into the system.
 The *Forms Not Received List* shows the barcodes for forms that the system has
 not yet intaken.
 
-
 ### Results Exports
 
 The *Downloads* section allows Super Administrators to export both simple and
 deteailed results views.  The *All Candidate Votes* download shows a simple
-spreadsheet of the leading candidates and their votes accross all ballots. The 
+spreadsheet of the leading candidates and their votes accross all ballots. The
 same for *Active Candidate Votes* which only shows votes for active candidates.
 The *Result Form List* returns a detailed file of the results entered for every
 result form and associated information about that result form, e.g. gender,