Documentation theme & format improvements

README.md

@@ -1,4 +1,4 @@
-![](docs/img/lpl-logo.png)
+![](docs/_static/lpl-logo.png)
 
 [![Build Status](https://github.com/OrcaCollective/OpenOversight/actions/workflows/publish.yml/badge.svg)](https://github.com/OrcaCollective/OpenOversight/actions/workflows/publish.yml)
 [![Documentation](https://img.shields.io/badge/docs-main-yellow)](https://orcacollective.github.io/OpenOversight/)

README_OLD.md

@@ -1,4 +1,4 @@
-![](docs/img/lpl-logo.png)
+![](docs/_static/lpl-logo.png)
 
 # OpenOversight [![Build Status](https://travis-ci.org/lucyparsons/OpenOversight.svg?branch=develop)](https://travis-ci.org/lucyparsons/OpenOversight) [![Coverage Status](https://coveralls.io/repos/github/lucyparsons/OpenOversight/badge.svg?branch=develop)](https://coveralls.io/github/lucyparsons/OpenOversight?branch=develop) [![Documentation Status](https://readthedocs.org/projects/openoversight/badge/?version=latest)](https://openoversight.readthedocs.io/en/latest/?badge=latest) [![Join the chat at https://gitter.im/OpenOversight/Lobby](https://badges.gitter.im/OpenOversight/Lobby.svg)](https://gitter.im/OpenOversight/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 

docs/advanced_csv_import.md

@@ -68,7 +68,7 @@ This can only be prevented by not including the column in the csv at all.
 Formats:
 - `date` - The date should be provided in `YYYY-MM-DD` format.
 - `time` - Time should be provided in `HH:MM:SS` 24h-format in the respective timezone.
-- `DEPARTMENT_STATE` - The department state should be provided in the `standard two-letter abbreviation <https://www.faa.gov/air_traffic/publications/atpubs/cnt_html/appendix_a.html>`_ format.
+- `DEPARTMENT_STATE` - The department state should be provided in the [standard two-letter abbreviation](https://www.faa.gov/air_traffic/publications/atpubs/cnt_html/appendix_a.html) format.
 
 
 The `id` field
@@ -88,8 +88,8 @@ Officers csv
 - Optional: `last_name, first_name, middle_initial, suffix, race, gender, employment_date, birth_year, unique_internal_identifier`
 - Ignored: `badge_number, job_title, most_recent_salary, unique_identifier` (Unused but command will not fail when field is present)
 
-Details
---------
+### Details
+
 - `department_name` - Name of department exactly as it is in the server database.
    This needs to match the department name provided with the command.
 - `department_state` - Name of department state exactly as it is in the server database, which will be the
@@ -112,8 +112,8 @@ Assignments csv
 - Required: `id, officer_id, job_title`
 - Optional: `badge_number, unit_id, unit_name, start_date, resign_date`
 
-Details
---------
+### Details
+
 - `officer_id` - Number referring to `id` of existing officer or string starting with `#` referring to a newly created officer in the provided officers csv.
 - `badge_number` - Any string that represents the star or badge number of the officer. In some departments this number changes with the assignment.
 - `job_title` - The job title, will be created if it does not exist.
@@ -122,8 +122,8 @@ Details
 - `start_date` - [Start date](https://help.highbond.com/helpdocs/analytics/13/user-guide/en-us/Content/table_definition/c_formats_of_date_and_time_source_data.htm) of this assignment.
 - `resign_date` - [End date](https://help.highbond.com/helpdocs/analytics/13/user-guide/en-us/Content/table_definition/c_formats_of_date_and_time_source_data.htm) of this assignment.
 
-Special Flag
--------------
+### Special Flag
+
 The `--overwrite-assignments` in the command can be used to not merge new with existing assignments.
 Instead, all existing assignments belonging to officers named in the `officer_id` column are deleted first,
 before the new assignments contained in the provided csv are created in the database.
@@ -136,8 +136,8 @@ Salaries csv
 - Required: `id, officer_id, salary, year`
 - Optional: `overtime_pay, is_fiscal_year`
 
-Details
---------
+### Details
+
 - `officer_id` - Integer referring to `id` of existing officer or string starting with `#` referring to a newly created officer in the provided officers csv.
 - `salary` - Number representing the officer's salary in the given year.
 - `year` - Integer, the year this salary information refers to.
@@ -151,12 +151,12 @@ Incidents csv
 - Optional: `date, time, report_number, description, street_name, cross_street1, cross_street2, city, state, zip_code,
   created_by, last_updated_by, officer_ids, license_plates`
 
-Details
---------
+### Details
+
 - `department_name` - Name of department exactly as in the server database.
    This needs to match the department name provided with the command.
 - `department_state` - Name of department state exactly as it is in the server database, which will be the
-   `standard two-letter abbreviation <https://www.faa.gov/air_traffic/publications/atpubs/cnt_html/appendix_a.html>`_ for the department's respective location.
+   [standard two-letter abbreviation](https://www.faa.gov/air_traffic/publications/atpubs/cnt_html/appendix_a.html) for the department's respective location.
 - `date` - [Date](https://help.highbond.com/helpdocs/analytics/13/user-guide/en-us/Content/table_definition/c_formats_of_date_and_time_source_data.htm) of the incident
 - `time` - [Time](https://help.highbond.com/helpdocs/analytics/13/user-guide/en-us/Content/table_definition/c_formats_of_date_and_time_source_data.htm) of the incident
 - `report_number` - String representing any kind of number assigned to complaints or incidents by the police department.
@@ -180,8 +180,8 @@ Links csv
 - Required: `id, url`
 - Optional: `title, link_type, description, author, created_by, officer_ids, incident_ids`
 
-Details
---------
+### Details
+
 - `url` - Full url of the link starting with `http://` or `https://`.
 - `title` - Text that will be displayed as the link.
 - `description` - A short description of the link.

docs/conf.py

@@ -71,7 +71,33 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+# ░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓██████▓▒░░▒▓███████▓▒░░▒▓███████▓▒░░▒▓█▓▒░▒▓███████▓▒░ ░▒▓██████▓▒░░▒▓█▓▒░
+# ░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░
+# ░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░      ░▒▓█▓▒░
+# ░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░▒▓████████▓▒░▒▓███████▓▒░░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒▒▓███▓▒░▒▓█▓▒░
+# ░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░
+# ░▒▓█▓▒░░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░
+#  ░▒▓█████████████▓▒░░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░░▒▓██████▓▒░░▒▓█▓▒░
+# NB (MSB 2024-08-30): I am doing some very funky CSS injections here to make things
+# look appropriate (since the Alabaster theme doesn't expose a ton of options).
+# The `body_text` option is technically a color override, but it's used here make
+# the text width more reasonable.
+# See more of the configuration options here:
+# https://alabaster.readthedocs.io/en/latest/customization.html
+html_theme_options = {
+    # Set a hard width for the sidebar to keep the title text and logo consistent
+    "sidebar_width": "255px",
+    # Make the sidebar fixed so it scrolls along with the user
+    "fixed_sidebar": True,
+    # Use the LPL logo in the docs
+    "logo": "lpl-logo.png",
+    # Include the project name below the LPL logo
+    "logo_name": True,
+    # Make the page width larger, but with a minimum of 800px at the smallest
+    "page_width": "max(60%, 800px)",
+    # Hack to allow the body content to expand to fill the whole page box
+    "body_text": "#3E4349;max-width: unset;",
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,