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

@@ -62,7 +62,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

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:

docs/source/main/retroarcher.rst → docs/source/src/retroarcher.rst

@@ -1,4 +1,4 @@
-.. include:: ../global.rst
+.. include:: global.rst
 
 :modname:`retroarcher`
 ----------------------

docs/source/toc.rst

@@ -19,17 +19,17 @@
 
 .. toctree::
    :maxdepth: 0
-   :caption: Code
+   :caption: Source Code
    :titlesonly:
 
-   main/retroarcher
-   pyra_docs/pyra
-   pyra_docs/config
-   pyra_docs/definitions
-   pyra_docs/hardware
-   pyra_docs/helpers
-   pyra_docs/locales
-   pyra_docs/logger
-   pyra_docs/threads
-   pyra_docs/tray_icon
-   pyra_docs/webapp
+   src/retroarcher
+   src/common/common
+   src/common/config
+   src/common/definitions
+   src/common/hardware
+   src/common/helpers
+   src/common/locales
+   src/common/logger
+   src/common/threads
+   src/common/tray_icon
+   src/common/webapp

requirements.txt

@@ -5,13 +5,15 @@ Flask-Babel==4.0.0
 furo==2024.7.18
 GPUtil==1.4.0
 IPy==1.01
-m2r2==0.3.3.post2
+myst-parser==4.0.0
 numexpr==2.10.1
 numpydoc==1.7.0
 Pillow==9.5.0
+polib==1.2.0
 psutil==6.0.0
 pyadl==0.1
 pyamdgpuinfo==2.1.6; sys_platform == 'Linux'
 pystray==0.19.5
 requests==2.32.3
 Sphinx==7.2.6
+werkzeug==3.0.3