Start working on stubs for 2.6.0 (extensions, etc.).

Switch to PyPi trusted publisher.

.github/workflows/default.yml

@@ -1,42 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches:
-      - master
-
-jobs:
-  build:
-
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/checkout@v1
-    # Standard drop-in approach that should work for most people.
-    - uses: ammaraskar/sphinx-action@master
-      env:
-        PYTHONPATH: .
-      with:
-        pre-build-command: "apt-get update -y && apt-get install -y libgl1-mesa-glx && cp stubs/2.3.0/mobase.pyi docs/mobase.py"
-        docs-folder: "docs/"
-
-    # Publish built docs to gh-pages branch.
-    # ===============================
-    - name: Commit documentation changes
-      run: |
-        git clone https://github.com/Holt59/mo2-pystubs-generation.git --branch gh-pages --single-branch gh-pages
-        cp -r docs/build/html/* gh-pages/
-        cd gh-pages
-        git config --local user.email "action@github.com"
-        git config --local user.name "GitHub Action"
-        git add .
-        git commit -m "Update documentation." -a || true
-        # The above command will fail if no changes were present, so we ignore
-        # that.
-
-    - name: Push changes
-      uses: ad-m/github-push-action@master
-      with:
-        branch: gh-pages
-        directory: gh-pages
-        github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/documentation.yml

@@ -0,0 +1,39 @@
+name: Build Documentation
+
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.12
+      - uses: abatilo/actions-poetry@v2
+      - name: Install
+        run: poetry install
+      - name: Install libgl1
+        run: sudo apt install -y libgl1 libegl1 libglib2.0-0 libxkbcommon0 libdbus-1-3
+      - name: Copy stubs
+        run: |
+          mkdir -p docs/src
+          cp -r stubs/2.5.2/mobase-stubs docs/src/mobase
+      - name: Build
+        run: poetry run sphinx-build -b html docs/source docs/build
+        env:
+          PYTHONPATH: docs
+      - if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+        name: Deploy Documentation
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          ssh-key: ${{ secrets.DEPLOY_KEY }}
+          repository-name: ModOrganizer2/python-plugins-doc
+          branch: master
+          folder: docs/build

.github/workflows/linting.yml

@@ -0,0 +1,20 @@
+name: Check Linting
+
+on: [push, pull_request]
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.12
+      - uses: abatilo/actions-poetry@v2
+      - name: Install
+        run: |
+          poetry install
+      - name: Lint
+        run: |
+          poetry run poe lint

.github/workflows/pull_request.yml

@@ -1,18 +0,0 @@
-name: CI
-
-on: [pull_request]
-
-jobs:
-  build:
-
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/checkout@v1
-    # Standard drop-in approach that should work for most people.
-    - uses: ammaraskar/sphinx-action@master
-      env:
-        PYTHONPATH: .
-      with:
-        pre-build-command: "apt-get update -y && apt-get install -y libgl1-mesa-glx && cp stubs/2.3.0/mobase.pyi docs/mobase.py"
-        docs-folder: "docs/"

.github/workflows/pypi-publish.yml

@@ -0,0 +1,57 @@
+# This workflows will upload a Python Package using Twine when a release is created
+# For more information see: https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#publishing-to-package-registries
+
+name: Publish Python 🐍 distribution 📦 to PyPI and TestPyPI
+
+on:
+  push:
+    tags: ["*"]
+
+jobs:
+  build:
+    name: Build distribution 📦
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Replace string
+        uses: frabert/replace-string-action@v1.1
+        id: version
+        with:
+          string: ${{ github.ref_name }}
+          pattern: "v?([0-9][.][0-9][.][0-9]).*"
+          replace-with: "$1"
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.12
+      - uses: abatilo/actions-poetry@v2
+      - name: Build
+        run: |
+          cd stubs/setup
+          mkdir mobase-stubs
+          cp -r ../${{ steps.version.outputs.replaced }}/mobase-stubs/* mobase-stubs/
+          sed -i 's/__version__ = ".*"/__version__ = "${{ github.ref_name }}"/' mobase-stubs/__init__.pyi
+          TAG=${{ github.ref_name }}
+          poetry version ${TAG#v}
+          poetry build
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v3
+        with:
+          name: python-package-distributions
+          path: stubs/setup/dist/
+
+  publish-to-pypi:
+    name: Publish Python 🐍 distribution 📦 to PyPI
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v3
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -2,9 +2,10 @@
 .mypy_cache
 __pycache__
 .vscode
+**/*.egg-info
 
 # The 'bin/' directory:
 bin
 docs/build
 docs/mobase.py
-docs/source/api
+docs/source/api

README.md

@@ -1,6 +1,6 @@
 # Mod Organizer 2 - Python stubs generation
 
-This little project can be used to generate python stubs (`.pyi` file) for the MO2 python
+This project can be used to generate python stubs (`.pyi` file) for the MO2 python
 interface `mobase`.
 
 ## Using the stubs
@@ -16,119 +16,103 @@ MO2.
 You can install stubs for a specific version of MO2:
 
 ```bash
-pip install mobase-stubs==2.3.2.*
-```
-
-If you want development stubs, you can install them this way:
-```bash
-# Clone this repository:
-git clone https://github.com/ModOrganizer2/pystubs-generation.git
-
-# Install the stubs:
-cd pystubs-generation/stubs/setup
-pip install .
+pip install mobase-stubs==2.5.*
 ```
 
 Some words of warning:
+
 - The stubs are as correct as possible, but some errors are expected.
-- If you see a `InterfaceNotImplemented` class anywhere in the stubs, it means that a proper interface is
-    currently not available.
-- Some classes are said (in the stubs) to inherit `QWidget` or `QObject`. This is true on the C++ side but NOT
-    on the python side. The inheritance is only added to help with auto-completion since these classes also
-    override `__getattr__` to dispatch to the underlying `QWidget` or `QObject`. Some things might not work as
-    expected with these class (e.g., `isintance(myObject, QObject)` will return `False`), which is why a
-    `_object()` and `_widget()` method is also provided.
+- Some classes are said (in the stubs) to inherit `QWidget` or `QObject`. This is true
+  on the C++ side but NOT on the python side. The inheritance is only added to help with
+  auto-completion since these classes also override `__getattr__` to dispatch to the
+  underlying `QWidget` or `QObject`. Some things might not work as expected with these
+  class (e.g., `isinstance(myObject, QObject)` will return `False`), which is why a
+  `_object()` and `_widget()` method is also provided.
 
 ## Generating the stubs
 
 The stubs are generated using python by parsing the `mobase` module.
-You need the version of python that matches your current MO2 installation: e.g., if you have a `python38.dll` in
-your MO2 installation path, then you need **python 3.8**.
+You need the version of python that matches your current MO2 installation: e.g., if you
+have a `python310.dll` in your MO2 installation path, then you need **Python 3.10**.
 
 To generate the stubs, you can run:
 
-```
-# Change the output folder to whatever you want:
-python main.py -c configs\config-2.3.yml -o stubs\setup\mobase-stubs\__init__.pyi ${MO2_INSTALL_PATH}
+```bash
+# install the package
+poetry install
+
+# change the output folder to whatever you want
+mo2-stubs-generator -c configs/config-2.4.yml -o mobase-stubs ${MO2_INSTALL_PATH}
 ```
 
-Where `${MO2_INSTALL_PATH}` is the path to your MO2 installation (the one containing `ModOrganizer.exe`).
+Where `${MO2_INSTALL_PATH}` is the path to your MO2 installation (the one
+containing `ModOrganizer.exe`).
 
-The latest stubs are kept under `stubs/setup/mobase-stubs/__init__.pyi`, and when a new version is released,
-the stubs are backed-up under `stubs/x.y.z/mobase.pyi`.
+The stubs are generated under `stubs/setup/mobase-stubs` by default, you
+can change the output file by using the `-o` option.
+The stubs under `stubs/setup/mobase-stubs` should not be committed as these are
+generated from the version stubs under `stubs/${VERSION}/mobase-stubs`.
 
+A few options are available for `mo2-stubs-generator`:
 
-If you do not specify a `-o` option, output will go to `stdout`, so you should redirect.
-Warning and "critical" messages are printed to `stderr`.
-
-A few options are available for `main.py`:
-
-```
-usage: Stubs generator for the MO2 python interface [-h] [-o OUTPUT] [-v] [-c CONFIG] INSTALL_DIR
+```bash
+$ mo2-stubs-generator --help
+usage: stubs generator for the MO2 python interface [-h] [-o OUTPUT] [-v] [-c CONFIG] INSTALL_DIR
 
 positional arguments:
   INSTALL_DIR           installation directory of Mod Organizer 2
 
-optional arguments:
+options:
   -h, --help            show this help message and exit
   -o OUTPUT, --output OUTPUT
-                        output file (output to stdout if not specified)
+                        output folder (default stubs/setup/mobase-stubs)
   -v, --verbose         verbose mode (all logs go to stderr)
   -c CONFIG, --config CONFIG
                         configuration file
 ```
 
-The stubs generator will try hard to find a valid stubs for all classes and methods of `mobase`.
-A lot of information is available through the `-v` options. Without it, only conversions or fixes
-considered "strange" will be outputed.
-For instance, here is the output with the current `config-2.3.yml` file:
-
-```
-WARNING: Replacing IOrganizer::FileInfo with FileInfo.
-WARNING: Replacing IOrganizer::FileInfo with FileInfo.
-WARNING: Replacing IPluginInstaller::EInstallResult with InstallResult.
-WARNING: Replacing IPluginInstaller::EInstallResult with InstallResult.
-```
-
-As you can see, only a few types were manually fixed (specified in `config-2.3.yml`).
+The stubs generator will try hard to find a valid stubs for all classes
+and methods of `mobase`.
+A lot of information is available through the `-v` options. Without it,
+only conversions or fixes considered "strange" will be shown.
 
 ## Configuration file
 
-The configuration file contains information for the stubs that cannot be deduced by `main` (or are too
-complex to deduce), and the documentation for everything.
+The configuration file contains information for the stubs that cannot be
+deduced by `main` (or are too complex to deduce), and the documentation for everything.
 
 ## Uploading the stubs to pypi
 
-The upload of the stubs to https://pypi.org/project/mobase-stubs/ has to be done manually. Here
-are the steps:
+The upload of the stubs to [https://pypi.org/project/mobase-stubs/](https://pypi.org/project/mobase-stubs/)
+should be done automatically when a new Github tag is pushed.
 
-1. Check the version of the stubs:
-  - The version is specified in the configuration file. If you need to modify the stubs of the
-    current version, you need to add a `.postX` after the version since PyPi does not allow
-    re-upload of the same release.
-2. Generate the stubs using the procedure above. You should generate the stubs under `stubs/setup/mobase-stubs/__init__.pyi`.
-3. If necessary, update the dependencies in `setup.py` (`PyQt5-stubs` version and python version).
-4. Go to `stubs/setup` and run:
+## Extras — Using `mobase` in a Python interpreter
+
+It is possible to start a (i)python interpreter with `mobase` imported by running
 
 ```bash
-python setup.py sdist bdist_wheel
-twine upload dist/*
+python -i -m mo2.stubs.generator.loader ${MO2_INSTALL_PATH}
 ```
 
-You need to set the environment variables `TWINE_USERNAME` and `TWINE_PASSWORD` to appropriate values
-before running `twine upload`.
+You can also import `mobase` in your code using the following (after installing
+this package):
 
-## Extras — Starts a python interpreter with `mobase`
+```python
+from mo2.stubs.generator import load_mobase
 
-It is possible to start a (i)python interpret with `mobase` imported by running:
+mobase = load_mobase(MO2_INSTALL_PATH)
 
-```
-python -im generator.loader ${MO2_INSTALL_PATH}
+# the above will probably not give you type-completion in your IDE or typing, so
+# you can use the following (if the stubs are installed)
+load_mobase(MO2_INSTALL_PATH)
+import mobase
+import mobase.widgets
 ```
 
-This has no real usage except for MO2 developers since most classes from the `mobase` module cannot be instantiated.
+**Note:** Most classes in `mobase` cannot be instantiated, so this is mostly intended
+for MO2 developers.
 
-# License
+## License
 
 The MIT License (MIT)
 
@@ -138,4 +122,4 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
 
 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
-See [LICENSE](LICENSE).
+See [LICENSE](LICENSE).

docs/Makefile

@@ -1,20 +0,0 @@
-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = build
-
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-.PHONY: help Makefile
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -1,35 +0,0 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=source
-set BUILDDIR=build
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
-	exit /b 1
-)
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-
-:end
-popd

docs/requirements.txt

@@ -1,4 +0,0 @@
-sphinx-rtd-theme
-sphinx-autodoc-typehints
-sphinx-automodapi
-PyQt5

docs/source/conf.py

@@ -10,21 +10,13 @@
 # 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
-
-sys.path.insert(0, os.path.abspath("../../stubs/2.3rc1/"))
-
 
 # -- Project information -----------------------------------------------------
 
 project = "MO2 Python Plugin API"
-copyright = "2020, Holt59"
+copyright = "2023, Holt59"
 author = "Holt59"
 
-# The full version, including alpha/beta/rc tags
-release = "2.3rc1"
-
 
 # -- General configuration ---------------------------------------------------
 
@@ -35,8 +27,9 @@ extensions = [
     "sphinx.ext.autodoc",
     "sphinx_autodoc_typehints",
     "sphinx.ext.napoleon",
+    "autoapi.extension",
     # "sphinx.ext.autosummary",
-    "sphinx_automodapi.automodapi",
+    # "sphinx_automodapi.automodapi",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -47,6 +40,9 @@ templates_path = ["_templates"]
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+autoapi_dirs = ["../src"]
+autoapi_member_order = "groupwise"
+
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -64,7 +60,10 @@ html_sidebars = {
     "**": ["globaltoc.html", "relations.html", "sourcelink.html", "searchbox.html"]
 }
 
+html_favicon = "mo2.ico"
+
 # 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,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+# html_static_path = ["_static"]
+html_extra_path = [".nojekyll"]

docs/source/index.rst

@@ -18,7 +18,6 @@ This documentation is dedicated to writting MO2 **Python** plugins.
    plugin-types
    writing-plugins
    faq
-   mobase
 
 
 

docs/source/mobase.rst

@@ -1,11 +0,0 @@
-``mobase`` API
-==============
-
-.. currentmodule:: mobase
-
-.. automodapi:: mobase
-   :no-inheritance-diagram:
-   :no-heading:
-
-.. toctree::
-   :maxdepth: 4

docs/source/modules.rst

@@ -1,7 +0,0 @@
-mobase
-======
-
-.. toctree::
-   :maxdepth: 4
-
-   mobase

docs/source/plugin-types.rst

@@ -64,10 +64,8 @@ These plugins (shall eventually) implement all the game specific features and fu
 able to add support for further games.
 The plugin is also responsible to help MO determine if (and where) the game is installed in the first place.
 Since supporting a game properly requires extensions in many places of the UI.
-To allow this without creating one huge plugin interface that involves every aspect of MO, game plugins
-expose a *feature list*.
-The list of possible features can be found in the "game_features" project and each feature can itself be
-considered a plugin interface.
+To allow this without creating one huge plugin interface that involves every aspect of MO,
+game plugins can register only the features they need to MO2 using :meth:`registerFeature<mobase.IGameFeatures.registerFeature>`
 
 As an example for a game feature take BSA invalidation: If the game requires BSA invalidation it will implement
 this feature.
@@ -147,4 +145,4 @@ File Mappings
 
 This interface allows plugins to add virtual file (or directory) links to the virtual file system in addition to the
 mod files.
-Profile-local save games, ini-files and load-orders are all implemented this way in MO2.
+Profile-local save games, ini-files and load-orders are all implemented this way in MO2.