Stabilize CI and docs builds while adding test coverage and code quality tooling

.github/workflows/ci.yml

@@ -19,19 +19,19 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
         cache: 'pip'
 
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install -e .
-        pip install pytest pytest-cov flake8
+        pip install -e ".[dev]"
+        pip install flake8
 
     - name: Lint with flake8
       run: |
@@ -43,13 +43,12 @@ jobs:
 
     - name: Run tests
       run: |
-        pytest --cov=qbiocode --cov-report=xml --cov-report=term
-      continue-on-error: true
+        python -m pytest --cov=qbiocode --cov-report=xml --cov-report=term
 
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v4
+      uses: codecov/codecov-action@v6
       with:
-        file: ./coverage.xml
+        files: ./coverage.xml
         flags: unittests
         name: codecov-${{ matrix.os }}-py${{ matrix.python-version }}
       continue-on-error: true
@@ -60,18 +59,19 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
 
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
-        python-version: '3.10'
+        python-version: '3.12'
         cache: 'pip'
 
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install flake8 black isort mypy
+        pip install -e ".[dev]"
+        pip install isort
 
     - name: Check code formatting with black
       run: black --check --diff qbiocode/
@@ -91,19 +91,23 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
 
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.10'
         cache: 'pip'
 
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install -e .
-        pip install sphinx sphinx-rtd-theme
+        pip install -e ".[docs]"
+
+    - name: Install pandoc
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y pandoc
 
     - name: Build documentation
       run: |
@@ -112,7 +116,7 @@ jobs:
       continue-on-error: true
 
     - name: Upload documentation artifacts
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v6
       with:
         name: documentation
         path: docs/build/html/

.github/workflows/release.yml

@@ -1,5 +1,8 @@
 name: Release
 
+permissions:
+  contents: write
+
 on:
   release:
     types: [published]
@@ -12,10 +15,10 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
 
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.10'
 
@@ -39,14 +42,9 @@ jobs:
 
     - name: Upload release assets
       if: github.event_name == 'release'
-      uses: actions/upload-release-asset@v1
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      with:
-        upload_url: ${{ github.event.release.upload_url }}
-        asset_path: ./dist/*.whl
-        asset_name: qbiocode-${{ github.event.release.tag_name }}-py3-none-any.whl
-        asset_content_type: application/zip
+      run: gh release upload "${{ github.event.release.tag_name }}" dist/*.whl --clobber
       continue-on-error: true
 
   create-zenodo-release:
@@ -57,7 +55,7 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
 
     - name: Zenodo release notification
       run: |

.gitignore

@@ -18,6 +18,13 @@ dist/
 build/
 *.whl
 
+# Testing results
+.coverage
+htmlcov/
+.coverage.*
+nosetests.xml
+coverage.xml
+
 # IDE
 .DS_Store
 .vscode/

CONTRIBUTING.md

@@ -56,7 +56,7 @@ This project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participatin
 
 4. **Install Development Dependencies** (optional)
    ```bash
-   pip install pytest pytest-cov black flake8 mypy
+   pip install -e ".[dev]"
    ```
 
 5. **Verify Installation**
@@ -164,7 +164,7 @@ from qbiocode.learning import compute_qsvc
 3. **Test Your Changes**
    ```bash
    # Run existing tests
-   pytest tests/
+   python -m pytest
 
    # Check code style
    black qbiocode/

README.md

@@ -90,6 +90,18 @@ pip install --force-reinstall xgboost
 
 For detailed installation instructions, see the [Installation Guide](https://ibm.github.io/QBioCode/installation.html).
 
+### Running Tests
+
+```bash
+# Install the package with development dependencies
+pip install -e ".[dev]"
+
+# Run the test suite
+python -m pytest
+```
+
+The current test suite focuses on utility modules and data-generation helpers that do not require a full runtime setup for all optional quantum workflows.
+
 ### Basic Usage
 
 ```python

docs/source/api_overview.rst

@@ -45,7 +45,7 @@ Multiple models can be run via the following
 Classical Models
 """"""""""""""""
 
-QBioCode provides classical machine learning models from `scikit-learn <https://scikit-learn.org/>`_ for baseline comparisons and benchmarking against quantum models.
+QBioCode provides classical machine learning models from `scikit-learn <https://scikit-learn.org/>`__ for baseline comparisons and benchmarking against quantum models.
 
 .. autosummary::
     ~qbiocode.learning.compute_dt.compute_dt
@@ -291,4 +291,3 @@ Generated datasets are saved with:
 
 References
 ^^^^^^^^^^
-

docs/source/apps/sage.rst

@@ -154,10 +154,11 @@ This trains QSage on historical QProfiler data and generates predictions for all
 Train with Random Forest only:
 
 .. code-block:: bash
-qsage --input qprofiler_results.csv --output results/ --model-type rf
 
-# Or train MLP sub-sages
-qsage --input qprofiler_results.csv --output results/ --model-type mlp
+   qsage --input qprofiler_results.csv --output results/ --model-type rf
+
+   # Or train MLP sub-sages
+   qsage --input qprofiler_results.csv --output results/ --model-type mlp
 
 
 Train with custom seed and test size:
@@ -166,11 +167,12 @@ Train with custom seed and test size:
 
    qsage --input data.csv --output results/ --seed 123 --test-size 0.3
 
-Train both Random Forest and MLP:
+Train with a custom MLP iteration count:
 
 .. code-block:: bash
-# Train MLP with more epochs
-qsage --input data.csv --output results/ --model-type mlp --n-iter 2000
+
+   # Train MLP with more epochs
+   qsage --input data.csv --output results/ --model-type mlp --n-iter 2000
 
 
 **Output Files**
@@ -439,4 +441,4 @@ QSage can reveal which complexity features are most predictive of model performa
 .. admonition:: Reference
    :class: tip
 
-   For implementation details, see ``apps/sage/sage.py`` in the QBioCode repository.
+   For implementation details, see ``apps/sage/sage.py`` in the QBioCode repository.

docs/source/citing.rst

@@ -1,10 +1,7 @@
 .. _citing:
 
-Citing 
-===============
-
 Citing qbiocode
---------------
+===============
 
 If qbiocode is integral to a scientific publication, please cite it.
 A paper describing qbiocode has been published in the :

docs/source/conf.py

@@ -142,7 +142,8 @@ def run_apidoc(app):
 html_show_sourcelink = False
 
 html_logo = "_static/QBioCode_logo.png"
-html_favicon = "_static/favicon.ico"
+if os.path.exists(os.path.join(os.path.dirname(__file__), "_static", "favicon.ico")):
+    html_favicon = "_static/favicon.ico"
 
 html_theme_options = {
     "icon_links": [

pyproject.toml

@@ -84,8 +84,10 @@ dev = [
     "pytest>=7.0",
     "pytest-cov>=4.0",
     "black>=23.0",
+    "isort>=5.0",
     "flake8>=6.0",
     "mypy>=1.0",
+    "types-PyYAML",
 ]
 all = [
     "hydra-core",
@@ -104,8 +106,10 @@ all = [
     "pytest>=7.0",
     "pytest-cov>=4.0",
     "black>=23.0",
+    "isort>=5.0",
     "flake8>=6.0",
     "mypy>=1.0",
+    "types-PyYAML",
 ]
 
 [project.scripts]
@@ -134,6 +138,10 @@ line-length = 100
 target-version = ['py310', 'py311', 'py312']
 include = '\.pyi?$'
 
+[tool.isort]
+profile = "black"
+line_length = 100
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 python_files = ["test_*.py"]
@@ -146,4 +154,4 @@ python_version = "3.10"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = false
-ignore_missing_imports = true
+ignore_missing_imports = true