refactor: restructure source code

.github/workflows/CI.yml

@@ -51,16 +51,16 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Install Python 3.9
+      - name: Setup Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: '3.12'
           architecture: ${{ matrix.architecture }}
 
-      - name: Set up Python Dependencies
+      - name: Setup Python Dependencies
         run: |
-          python -m pip install --upgrade pip setuptools
-          python -m pip install -r requirements-dev.txt --no-warn-script-location
+          python -m pip install --upgrade pip setuptools wheel
+          python -m pip install -r requirements-dev.txt
 
       - name: Compile Locale Translations
         run: |
@@ -108,7 +108,7 @@ jobs:
             --tb=native \
             --verbose \
             --color=yes \
-            --cov=pyra \
+            --cov=src \
             tests
 
       - name: Upload coverage

.github/workflows/localize.yml

@@ -6,9 +6,8 @@ on:
     branches: [master]
     paths:  # prevents workflow from running unless these files change
       - '.github/workflows/localize.yml'
-      - 'retroarcher.py'
       - 'locale/retroarcher.po'
-      - 'pyra/**.py'
+      - 'src/**.py'
       - 'web/templates/**'
   workflow_dispatch:
 
@@ -21,14 +20,14 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Install Python 3.9
+      - name: Install Python
         uses: actions/setup-python@v5  # https://github.com/actions/setup-python
         with:
-          python-version: '3.9'
+          python-version: '3.12'
 
-      - name: Set up Python 3.9 Dependencies
+      - name: Setup Python Dependencies
         run: |
-          python -m pip install --upgrade pip setuptools
+          python -m pip install --upgrade pip setuptools wheel
           python -m pip install -r requirements.txt
 
       - name: Update Strings

.gitignore

@@ -155,8 +155,6 @@ cython_debug/
 node_modules/
 *package-lock.json
 
-# RetroArcher directories
+# project files and directories
 logs/
-
-# RetroArcher files
 *config.ini

.readthedocs.yaml

@@ -8,9 +8,9 @@ version: 2
 
 # Set the version of Python
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
-    python: "3.9"
+    python: "3.12"
   jobs:
     pre_build:
       - python ./scripts/_locale.py --compile

Dockerfile

@@ -1,19 +1,29 @@
 # artifacts: false
 # platforms: linux/386,linux/amd64
-FROM python:3.9.6-slim-bullseye as retroarcher-base
+FROM python:3.12-slim-bookworm as retroarcher-base
 
 FROM retroarcher-base as retroarcher-build
 
+SHELL ["/bin/bash", "-o", "pipefail", "-c"]
+
 # install build dependencies
-RUN apt-get update -y \
-     && apt-get install -y --no-install-recommends \
-        build-essential \
-        nodejs \
-        npm \
-        pkg-config \
-        libopenblas-dev \
-    && apt-get clean \
-    && rm -rf /var/lib/apt/lists/*
+RUN <<_DEPS
+#!/bin/bash
+set -e
+
+dependencies=(
+  "build-essential"
+  "libjpeg-dev"  # pillow
+  "npm"  # web dependencies
+  "pkg-config"
+  "libopenblas-dev"
+  "zlib1g-dev"  # pillow
+)
+apt-get update -y
+apt-get install -y --no-install-recommends "${dependencies[@]}"
+apt-get clean
+rm -rf /var/lib/apt/lists/*
+_DEPS
 
 # python virtualenv
 RUN python -m venv /opt/venv
@@ -25,15 +35,23 @@ WORKDIR /build
 COPY . .
 
 # setup python requirements
-RUN python -m pip install --no-cache-dir --upgrade pip setuptools wheel && \
-    python -m pip install --no-cache-dir -r requirements.txt
+RUN <<_REQUIREMENTS
+#!/bin/bash
+set -e
+python -m pip install --no-cache-dir --upgrade pip setuptools wheel
+python -m pip install --no-cache-dir -r requirements.txt
+_REQUIREMENTS
 
 # compile locales
 RUN python scripts/_locale.py --compile
 
 # setup npm and dependencies
-RUN npm install && \
-    mv -f ./node_modules/ ./web/
+RUN <<_NPM
+#!/bin/bash
+set -e
+npm install
+mv -f ./node_modules/ ./web/
+_NPM
 
 # compile docs
 WORKDIR /build/docs
@@ -62,7 +80,7 @@ RUN groupadd -g 1000 retroarcher && \
 RUN mkdir -p /config
 VOLUME /config
 
-CMD ["python", "retroarcher.py"]
+CMD ["python", "./src/retroarcher.py"]
 
 EXPOSE 9696
-HEALTHCHECK --start-period=90s CMD python retroarcher.py --docker_healthcheck || exit 1
+HEALTHCHECK --start-period=90s CMD python ./src/retroarcher.py --docker_healthcheck || exit 1

docs/source/conf.py

@@ -6,24 +6,26 @@
 
 # standard imports
 from datetime import datetime
+import os
+import sys
 
 
 # -- Path setup --------------------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-import os
-import sys
 
 script_dir = os.path.dirname(os.path.abspath(__file__))  # the directory of this file
 source_dir = os.path.dirname(script_dir)  # the source folder directory
 root_dir = os.path.dirname(source_dir)  # the root folder directory
+src_dir = os.path.join(root_dir, 'src')  # the src folder directory
 
 try:
-    sys.path.insert(0, root_dir)
-    from pyra import definitions  # put this in a try/except to prevent flake8 warning
-except Exception:
+    sys.path.insert(0, src_dir)
+    from common import definitions  # put this in a try/except to prevent flake8 warning
+except Exception as e:
+    print(f"Unable to import definitions from {root_dir}: {e}")
     sys.exit(1)
 
 # -- Project information -----------------------------------------------------
@@ -42,10 +44,11 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'm2r2',  # enable markdown files
+    'myst_parser',  # enable markdown files
     'numpydoc',  # this automatically loads `sphinx.ext.autosummary` as well
     'sphinx.ext.autodoc',  # autodocument modules
     'sphinx.ext.autosectionlabel',
+    'sphinx.ext.intersphinx',  # link to other projects' documentation
     'sphinx.ext.todo',  # enable to-do sections
     'sphinx.ext.viewcode'  # add links to view source code
 ]
@@ -59,13 +62,16 @@
 exclude_patterns = ['toc.rst']
 
 # Extensions to include.
-source_suffix = ['.rst', '.md']
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
 
 
 # -- Options for HTML output -------------------------------------------------
 
 # images
-html_favicon = os.path.join(definitions.Paths().ROOT_DIR, 'web', 'images', 'retroarcher.ico')
+html_favicon = os.path.join(definitions.Paths().ROOT_DIR, 'web', 'images', 'favicon.ico')
 html_logo = os.path.join(definitions.Paths().ROOT_DIR, 'web', 'images', 'logo-circle.png')
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -102,3 +108,13 @@
 # disable epub mimetype warnings
 # https://github.com/readthedocs/readthedocs.org/blob/eadf6ac6dc6abc760a91e1cb147cc3c5f37d1ea8/docs/conf.py#L235-L236
 suppress_warnings = ["epub.unknown_project_files"]
+
+python_version = f'{sys.version_info.major}.{sys.version_info.minor}'
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/{}/'.format(python_version), None),
+}
+
+numpydoc_show_class_members = True
+numpydoc_show_inherited_class_members = False
+numpydoc_xref_param_type = True

docs/source/contributing/localization.rst

@@ -43,7 +43,7 @@ situations. For example the system tray icon is user interfacing and therefore s
 - In order for strings to be extracted from python code, the following lines must be added.
    .. code-block:: python
 
-      from pyra import locales
+      from common import locales
       _ = locales.get_text()
 
 - Wrap the string to be extracted in a function as shown.
@@ -76,8 +76,7 @@ any of the following paths are modified.
 
 .. code-block:: yaml
 
-   - 'retroarcher.py'
-   - 'pyra/**.py'
+   - 'src/**.py'
    - 'web/templates/**'
 
 When testing locally it may be desirable to manually extract, initialize, update, and compile strings.

docs/source/src/common/common.rst

@@ -0,0 +1,7 @@
+.. include:: ../global.rst
+
+:modname:`common.__init__`
+--------------------------
+.. automodule:: common
+    :members:
+    :show-inheritance:

docs/source/pyra_docs/pyra.rst → docs/source/src/common/config.rst

@@ -1,7 +1,7 @@
 .. include:: ../global.rst
 
-:modname:`pyra.__init__`
+:modname:`common.config`
 ------------------------
-.. automodule:: pyra
+.. automodule:: common.config
     :members:
     :show-inheritance:

docs/source/src/common/definitions.rst

@@ -0,0 +1,7 @@
+.. include:: ../global.rst
+
+:modname:`common.definitions`
+-----------------------------
+.. automodule:: common.definitions
+    :members:
+    :show-inheritance:

docs/source/src/common/hardware.rst

@@ -0,0 +1,7 @@
+.. include:: ../global.rst
+
+:modname:`common.hardware`
+--------------------------
+.. automodule:: common.hardware
+    :members:
+    :show-inheritance:

docs/source/pyra_docs/tray_icon.rst → docs/source/src/common/helpers.rst

@@ -1,7 +1,7 @@
 .. include:: ../global.rst
 
-:modname:`pyra.tray_icon`
+:modname:`common.helpers`
 -------------------------
-.. automodule:: pyra.tray_icon
+.. automodule:: common.helpers
     :members:
     :show-inheritance:

docs/source/src/common/locales.rst

@@ -0,0 +1,7 @@
+.. include:: ../global.rst
+
+:modname:`common.locales`
+-------------------------
+.. automodule:: common.locales
+    :members:
+    :show-inheritance:

docs/source/src/common/logger.rst

@@ -0,0 +1,7 @@
+.. include:: ../global.rst
+
+:modname:`common.logger`
+------------------------
+.. automodule:: common.logger
+    :members:
+    :show-inheritance:

docs/source/src/common/threads.rst

@@ -0,0 +1,7 @@
+.. include:: ../global.rst
+
+:modname:`common.threads`
+-------------------------
+.. automodule:: common.threads
+    :members:
+    :show-inheritance:

docs/source/pyra_docs/definitions.rst → docs/source/src/common/tray_icon.rst

@@ -1,7 +1,7 @@
 .. include:: ../global.rst
 
-:modname:`pyra.definitions`
+:modname:`common.tray_icon`
 ---------------------------
-.. automodule:: pyra.definitions
+.. automodule:: common.tray_icon
     :members:
     :show-inheritance:

docs/source/src/common/webapp.rst

@@ -0,0 +1,7 @@
+.. include:: ../global.rst
+
+:modname:`common.webapp`
+------------------------
+.. automodule:: common.webapp
+    :members:
+    :show-inheritance: