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

DOCKER_README.md

@@ -1,6 +1,8 @@
-### lizardbyte/retroarcher
+# Docker
 
-#### Using docker run
+## lizardbyte/retroarcher
+
+### Using docker run
 Create and run the container (substitute your `<values>`):
 
 ```bash
@@ -28,7 +30,7 @@ docker pull lizardbyte/retroarcher
 docker run -d ...
 ```
 
-#### Using docker-compose
+### Using docker-compose
 
 Create a `docker-compose.yml` file with the following contents (substitute your `<values>`):
 
@@ -63,7 +65,7 @@ docker-compose pull
 docker-compose up -d
 ```
 
-#### Parameters
+### Parameters
 You must substitute the `<values>` with your own settings.
 
 Parameters are split into two halves separated by a colon. The left side represents the host and the right side the
@@ -83,7 +85,7 @@ Therefore `-p 9696:9696` would expose port `9696` from inside the container to b
 | `-e PGID=<gid>`             | Group ID                                                                             | `1001`              |  False   |
 | `-e TZ=<timezone>`          | Lookup TZ value [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) | `America/New_York`  |   True   |
 
-#### User / Group Identifiers:
+### User / Group Identifiers:
 
 When using data volumes (-v flags) permissions issues can arise between the host OS and the container. To avoid this
 issue you can specify the user PUID and group PGID. Ensure the data volume directory on the host is owned by the same

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 base
 
-FROM retroarcher-base as retroarcher-build
+FROM base as 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,44 +35,72 @@ 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
 RUN sphinx-build -M html source build
 
-FROM retroarcher-base as retroarcher
+FROM base as app
 
 # copy app from builder
-COPY --from=retroarcher-build /build/ /app/
+COPY --from=build /build/ /app/
 
 # copy python venv
-COPY --from=retroarcher-build /opt/venv/ /opt/venv/
+COPY --from=build /opt/venv/ /opt/venv/
 # use the venv
 ENV PATH="/opt/venv/bin:$PATH"
 # site-packages are in /opt/venv/lib/python<version>/site-packages/
 
 # setup remaining env variables
 ENV RETROARCHER_DOCKER=True
-ENV TZ=UTC
+
+# network setup
+EXPOSE 9696
 
 # setup user
-RUN groupadd -g 1000 retroarcher && \
-    useradd -u 1000 -g 1000 retroarcher
+ARG PGID=1000
+ENV PGID=${PGID}
+ARG PUID=1000
+ENV PUID=${PUID}
+ENV TZ="UTC"
+ARG UNAME=lizard
+ENV UNAME=${UNAME}
 
-# create config directory
-RUN mkdir -p /config
+ENV HOME=/home/$UNAME
+
+# setup user
+RUN <<_SETUP_USER
+#!/bin/bash
+set -e
+groupadd -f -g "${PGID}" "${UNAME}"
+useradd -lm -d ${HOME} -s /bin/bash -g "${PGID}" -u "${PUID}" "${UNAME}"
+mkdir -p ${HOME}/.config/retroarcher
+ln -s ${HOME}/.config/retroarcher /config
+chown -R ${UNAME} ${HOME}
+_SETUP_USER
+
+# mounts
 VOLUME /config
 
-CMD ["python", "retroarcher.py"]
+USER ${UNAME}
+WORKDIR ${HOME}
 
-EXPOSE 9696
-HEALTHCHECK --start-period=90s CMD python retroarcher.py --docker_healthcheck || exit 1
+ENTRYPOINT ["python", "./src/retroarcher.py"]
+HEALTHCHECK --start-period=90s CMD python ./src/retroarcher.py --docker_healthcheck || exit 1

docs/source/about/docker.rst

@@ -1,4 +1,2 @@
-Docker
-------
-
-.. mdinclude:: ../../../DOCKER_README.md
+.. include:: ../../../DOCKER_README.md
+   :parser: myst_parser.docutils_

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.