CI Project Setup

Project Setup

.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+# This pipeline builds the documentation.
+name: docs
+
+on:
+  push:
+    branches: [ main ]
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+          cache: "pip"
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+          version: "1.3.2"
+      - name: Cache dependencies
+        id: cache-deps
+        uses: actions/cache@v2
+        with:
+          path: .venv
+          key: pydeps-${{ hashFiles('**/poetry.lock') }}
+      - name: Install the dependencies
+        run: poetry install --no-interaction --no-root --with dev
+        if: steps.cache-deps.outputs.cache-hit != 'true'
+      - name: Install the module
+        run: poetry install --with dev --no-interaction
+      - name: Generate the documentation
+        run: poetry run mkdocs gh-deploy --force

.github/workflows/test.yml

@@ -0,0 +1,54 @@
+# This pipeline checks whether the package
+# installs properly, passes unit tests and whether
+# the code formatting is right.
+name: build
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: ["3.12"]
+        poetry-version: ["1.8.3"]
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Run black formatting check
+        uses: psf/black@stable
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:  
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+          version: ${{ matrix.poetry-version }}
+      - name: Cache dependencies
+        id: cache-deps
+        uses: actions/cache@v2
+        with:
+          path: .venv
+          key: pydeps-${{ hashFiles('**/poetry.lock') }}
+      - name: Install the dependencies
+        run: poetry install --no-interaction --no-root --with dev
+        if: steps.cache-deps.outputs.cache-hit != 'true'
+      - name: Install the module
+        run: poetry install --with dev --no-interaction
+      - name: Run unit tests
+        run: poetry run pytest
+      - name: Run Ruff
+        run: poetry run ruff check .
+      - name: Run interrogate
+        run: poetry run interrogate src
+      - name: Run Pyright (type checking)
+        run: poetry run pyright

.gitignore

@@ -1,2 +1,2 @@
 .DS_Store
-*.lock
+poetry.lock

.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+repos:
+  - repo: https://github.com/python-poetry/poetry
+    rev: '1.8.3'
+    hooks:
+      - id: poetry-check
+      - id: poetry-lock
+      - id: poetry-export
+        args: ["-f", "requirements.txt", "-o", "requirements.txt"]
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: 'v0.0.245'
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+  - repo: https://github.com/psf/black
+    rev: 23.1.0
+    hooks:
+      - id: black
+  - repo: https://github.com/econchick/interrogate
+    rev: 1.5.0
+    hooks:
+      - id: interrogate
+        args: [--quiet, --fail-under=95]
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: poetry run pyright
+        language: node
+        pass_filenames: true
+        types: [python]

README.md

@@ -1,3 +1,70 @@
+[![Project Status: WIP – This project is currently under active development.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
+[![build](https://github.com/gordonkoehn/UsefulGnom/actions/workflows/test.yml/badge.svg)](https://github.com/gordonkoehn/UsefulGnom/actions/workflows/test.yml)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/charliermarsh/ruff)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+# UsefulGnom
+
+Python package for viral genomic analysis utilities.
+
+
+## Usage
+
+```python
+import usefulgnom as ug
+```
+
+
+### Setting up the repository
+
+To build the package and maintain dependencies, we use [Poetry](https://python-poetry.org/).
+In particular, it's good to install it and become familiar with its basic functionalities by reading the documentation. 
+
+To set up the environment (together with development tools), run:
+```bash
+$ poetry install --with dev
+$ poetry run pre-commit install
+```
+
+Then, you will be able to run tests:
+```bash
+$ poetry run pytest
+```
+... or check the types:
+```bash
+$ poetry run pyright
+```
+
+Alternatively, you may prefer to work with the right Python environment using:
+```bash
+$ poetry shell
+$ pytest
+```
+
+### Existing code quality checks
+The code quality checks run on GitHub can be seen in ``.github/workflows/test.yml``.
+
+We are using:
+
+  * [Ruff](https://github.com/charliermarsh/ruff) to lint the code.
+  * [Black](https://github.com/psf/black) to format the code.
+  * [Pyright](https://github.com/microsoft/pyright) to check the types.
+  * [Pytest](https://docs.pytest.org/) to run the unit tests.
+  * [Interrogate](https://interrogate.readthedocs.io/) to check the documentation.
+
+
+### Workflow
+
+We use [Feature Branch Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow),
+in which modifications of the code should happen via small pull requests.
+
+We recommend submitting small pull requests and starting with drafts outlining proposed changes.
+
+
+
+_____
+
+
 Auguste's scripts for 
  - 1) calculating basecnt coverage depth, 
  - 2) total coverage depth and 

docs/api/index.md

@@ -0,0 +1 @@
+# API

docs/contributing.md

@@ -0,0 +1 @@
+# Contributing

docs/tutorial/index.md

@@ -0,0 +1 @@
+# Tutorial

docs/workflows/index.md

@@ -0,0 +1 @@
+# Workflows

mkdocs.yml

@@ -0,0 +1,78 @@
+site_name: usefulgnom
+theme:
+  name: material
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - toc.integrate
+    - search.suggest
+    - search.highlight
+    - content.tabs.link
+    - content.code.annotation
+    - content.code.copy
+  language: en
+  palette:
+    - scheme: default
+      toggle:
+        icon: material/toggle-switch-off-outline 
+        name: Switch to dark mode
+      primary: teal
+      accent: purple 
+    - scheme: slate 
+      toggle:
+        icon: material/toggle-switch
+        name: Switch to light mode    
+      primary: teal
+      accent: lime
+
+repo_name: usefulgnom
+repo_url: https://github.com/gordonkoehn/usefulgnom
+
+plugins:
+  - search
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          options:
+            show_source: false
+            show_root_heading: true
+
+nav:
+  - Home: index.md
+  - Contributing: contributing.md
+  - Tutorial: tutorial/index.md
+  - API: api/index.md
+  - Workflows: workflows/index.md
+
+watch:
+  - src/usefulgnom
+
+extra:
+  social:
+    - icon: fontawesome/brands/github-alt
+      link: https://github.com/gordonkoehn/usefulgnom
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - admonition
+  - pymdownx.arithmatex:
+      generic: true
+  - footnotes
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.mark
+  - attr_list
+ # TODO (Gordon): cannot get this packages to be found my mkdocs 
+ # - pymdownx.emoji:
+ #     emoji_index: !!python/name:materialx.emoji.twemoji
+ #     emoji_generator: !!python/name:materialx.emoji.to_svg
+
+
+extra_javascript:
+  - javascripts/mathjax.js
+  - https://polyfill.io/v3/polyfill.min.js?features=es6
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js